feat: plugin API for agent options, metadata, composer and New workspace (#8744)

* feat(protocol): option controls, options patch, and provider.controls.list Add AgentOptionControl descriptors, snapshot options/controls, an options patch on agent.config.apply, provider.controls.list RPC, and server_info.features.providerOptionControls. featureValues stays accepted on the wire (COMPAT). * feat(server): fold featureValues into providerOptions and describe composer controls Providers emit option controls over top-level providerOptions keys; the daemon stores one options record per agent, merges config.json defaults as effective values, and applies patches live via AgentSession.applyOptions. Legacy featureValues (wire, stored records, profiles, schedules, hooks, MCP) fold into providerOptions; snapshots still carry features built from controls. Snapshot options expose only keys that have a control. * fix(server): address Phase 1 audit findings on option controls - Removing auto_accept (OpenCode, ACP) turns live approval off; ACP selects return to their session default. - agent.create.before hook featureValues edits override options the create already set. - Claude commits fast_mode only after the runtime accepts it. - Codex snapshots show a saved Fast preference as the tier the model resolves it to (AgentSession.displayOptions). - Profiles are folded into options in the daemon config store; the config API still answers with featureValues. - Snapshot options and provider.controls.list carry all effective options. - Test: Claude fast_mode survives a restart through stored providerOptions. * fix(server): keep snapshot options as configured, restore OMP baseline, cover options through public interfaces - Codex: drop displayOptions; a select choice may carry aliases so a saved Fast preference selects the model's Fast tier from options + controls alone. - OMP: removing fast_mode restores the runtime's starting setting. - ACP/Cursor removal tests run through real session initialization. - agent.config.apply of a non-control option reaches the provider and shows in the next snapshot (daemon e2e). - Daemon config store persists legacy-featureValues profiles as options on the next profile save. * fix(server): read a pre-v0.10 Codex fast_mode record as service_tier "fast" and store it that way A record holding `fast_mode: true` without `service_tier` ran Fast but the speed control showed Normal, and picking Normal then wrote "default". The Codex session now normalizes the old boolean at construction and reports the new shape through its existing options_changed event. * fix(server): show Fast for a stored Codex fast_mode: true without rewriting the record Reverts the storage migration from a987b4a43. The Codex speed control now takes its default from the session's current options with the same rule the runtime uses (an explicit service_tier wins; fast_mode: true applies only while service_tier is absent). This holds on create, resume, live apply and for config.json defaults, and stored options stay as set. * chore(website): regenerate the config schema for profile options * refactor(server): providers report option differences once, after create, resume and apply Providers used to write their own reports into the agent's options while a session was being created, resumed or updated, which needed a growing set of reconciliation, baseline and suppression rules to stay in step with the daemon. The contract is now transactional. A provider opens or updates with the options it is given and emits nothing while doing so; if the result differs it says so once, afterwards, as `options_changed`. Live apply hands the provider only the keys the patch sets and the daemon stores them onto the agent's current options when the provider accepts, so the last write wins. A change the provider makes on its own is stored and forwarded, not undone. Removing an option drops the key and sends nothing live. Controls carry no state; `options` is the only option state. A legacy `agent.create.before` hook's `featureValues` edits are applied as a patch over the returned options, so its deletions and replacements hold. The unreleased `aliases` field on option choices is gone; a pre-v0.10 Codex Fast preference is reported once as the model's tier id. * refactor(server): providers return what apply and open ended with instead of reporting it afterwards applyOptions returns the options the session ended up with and the session exposes its open difference as openOptionsPatch, so the manager stores the patch and the provider's answer in one step. Removal is an ordinary patch: the provider receives the default the key falls back to, or null, and returns what it kept. Controls no longer take a default from a stored legacy feature value. * fix(server): apply an old app's profile featureValues over the profile's stored options The unchanged app's profile form only knows the controls, so a name-only edit dropped options it never shows, such as sandbox_mode. Its featureValues now apply as a patch over the options already stored for the profile (null removes a key), and a write with no featureValues keeps them. * fix(server): ACP reports the selects it moved during open or apply as that call's result A config_option_update that arrived before the write response was emitted as an event on top of the result the manager stores. Notifications during open or apply now fold into the open patch or apply result, and a rejected apply reports what the agent moved since nothing is stored. Live options are validated with the creation schema. Tests drive a stdio ACP agent. * fix(server): providers validate live option patches and Claude reports Fast dropped by a model switch Live patches go through the schema used at creation. A Claude model switch that cannot keep Fast reports fast_mode as removed so the stored options match the session. * fix(server): Claude reports Fast as off, not removed, when a model switch drops it A removed key lets a config.json default of fast_mode: true fill back in while Fast is off at runtime. * fix(server): fold an old app's profile featureValues by the provider and options the write carries A write with options folds featureValues over those options. A write without them patches the stored options, unless the profile moved to another provider, which starts from no options. * docs(server): a rejected apply reports what the provider moved after the call ends * test(server): a patch key is resolved against nested configured defaults * test(server): a setting a plugin changes on its own is forwarded as options_changed * test(server): assert the forwarded plugin setting without nesting callbacks * test(server): removal of auto_accept returns ACP to asking; Claude keeps opening restrictions across a patch * fix(server): Codex returns the tier it resolved and drops a speed the new model lacks A live service_tier: fast is stored as the catalog's Fast tier id instead of a value the control cannot show, and a model switch to a model without the stored speed reports Normal so choosing a supporting model again does not bring the paid tier back. * fix(server): Claude applies only the keys a patch sets over its current options A Fast patch kept a copy of the options taken before the runtime answered, and assigning it afterwards dropped a patch that landed meanwhile. * fix(server): a plugin that moves settings and then refuses an apply reports what moved * refactor(server): the legacy featureValues folds take one named-input object * fix(server): a live patch is rejected for an option the session only reads at start, and opening reports every option it ended up with A stored option has to describe what runs. OpenCode, OMP and ACP now reject a live change to a key they apply only when the agent opens; Claude applies such a change from the next turn and rejects it while a turn is running. Opening reports every select or setting the session came up with, including ones nobody set, so a native default (Cursor opening with Fast on) is stored as option state like any other. * fix(server): Claude rejects a live change to an option it reads when the query starts Replacing a started query to apply the option would end its background shells and tasks. Once the query exists only Fast can change; before the first prompt every option still applies, because it is read when the query is built. * fix(server): a live options patch is rejected when the session cannot apply it A session with no applyOptions (Pi) now rejects a patch instead of storing a value that fails on reopen. Codex applies only service_tier, plan_mode and fast_mode live, since the approval policy and sandbox are fixed when the thread starts. Claude also rejects a launch option change while its first query is starting, after the options have been copied. * fix(server): plugins reject keys they do not report as settings, and Codex opening reports the speed it runs A plugin session applied the settings it knew and silently stored the rest; it now rejects a patch that names a key the plugin does not report. Codex opening on a model without the saved speed ran Normal while the stored options still said priority; opening now reports the tier it runs, as a later model switch does. * refactor(server): option helpers take named inputs, control types come from their schemas, and a plugin accepts launch options it opened with A whole profile is applied by the unchanged app, so a launch-only plugin option whose value has not changed must not fail the apply. applyProviderOptionsPatch and featuresFromControls take one object, and the protocol control types are inferred from the wire schemas. * fix(server): ACP reports a select that appears after startup with its native value A model switch can introduce a select (Cursor Fast) that the session did not have at open. Its value is now stored like any other native selection instead of being skipped because the previous snapshot did not name it. * fix(server): a loaded agent's options stay what its session opened with when a provider default is edited effectiveOptions was recomputed from the current config.json defaults on every state emission, so editing a default changed the snapshot of an agent whose session never received it. It is now computed when the session opens and moves only through an apply or an options_changed. Editing a default affects agents the next time they open. * fix(server): a live apply shows the merged defaults the provider was given in the options snapshot The snapshot took the raw patch, so a nested patch over configured defaults dropped the defaults the provider had accepted. The snapshot now takes what the provider was sent plus what it reports back; stored options still keep the raw patch. * fix(server): an option a session drops when opening is not brought back by a configured default The opening snapshot merged defaults over the options after the session's openOptionsPatch had removed a key. Defaults now merge into what the session was given and the patch applies after. * fix(server): Codex keeps the speed it opened with when the legacy Fast key is removed Opening moves a legacy fast_mode into service_tier, so removing fast_mode afterwards changed the runtime speed to Normal while the stored options still said Fast. Removing the alias now changes no speed. * fix(server): opening snapshots keep the defaults the session launched with, and config-change pushes carry legacy profile values An opening resolved defaults once for the session and again at registration; an edit in between showed options the session never received. Create, resume and reload now resolve once, before the provider opens, and registration starts from that. The daemon_config_changed push skipped the featureValues projection that config replies apply, so the unchanged app lost a profile's legacy values when any setting changed. * fix(server): every opening path hands registration the options it launched with Registration took the launch options as optional and reread the defaults when a path did not supply them, as provider-session import did. It is now required, so create, resume, reload and import each resolve once before opening. The option helpers take named inputs. * fix(server): a saved legacy Codex Fast preference wins over a configured service_tier default The defaults merge put a configured service_tier next to the agent's own legacy fast_mode, and Codex reads service_tier first, so the agent opened Normal. The agent's own alias now replaces the default of the key it stands for. * fix(server): Codex keeps a Fast chosen by alias as the catalog's tier id A live fast_mode or service_tier "fast" was stored as the alias while the apply reported the catalog id, so a later switch to a model with a different Fast id ran Fast under an option that said otherwise. The session now stores the id it accepted and drops the folded fast_mode. * fix(server): the legacy Codex Fast alias folds into one speed on apply and in configured defaults A patch with both speed keys left the alias in the stored options, so a reload started Fast again after the speed was removed; the apply now reports the folded alias. A configured fast_mode default now supplies the service_tier default, so removing an agent's own speed falls back to the configured Fast like opening does. * fix(server): an OMP replacement runtime starts with the Fast the session has now A restart (for example an approval-mode change) restored Fast from the options the session opened with, turning back on a Fast the user had switched off. The session now keeps the Fast it applied or the provider changed, which is what a replacement reads. * refactor(server): Codex's legacy fast_mode converts to service_tier where old data enters Stored records, config.json defaults, profiles, older clients' requests, MCP settings and plugin hooks go through convertLegacyOptions as they come in. Past that point the defaults merge, the manager and the Codex session never see fast_mode for Codex, so the alias branch in the defaults merge and Codex's fast_mode handling are deleted. * fix(server): a legacy hook's replaced speed and an apply request's options convert before they are compared or applied A hook that swaps the canonical speed it was sent for fast_mode is diffed in canonical form, so its replacement is not read as a deletion. An apply request carrying featureValues and options sends one options patch with options winning, so a superseded legacy value is never applied. * refactor(server): the agent manager converts Codex's legacy fast_mode for the adapter behind the provider id The rename is adapter-specific, so it lives where the provider id resolves to its adapter: AgentManager converts an agent's own options on create, resume, import, reload, apply and draft controls, following derivedFromProviderId, so a custom provider extending codex keeps working with a saved or requested fast_mode. Storage, MCP, schedules, hub and profiles pass options through. The featureValues-to-options fold stays provider-agnostic at the legacy edges. * fix(server): a rejected OpenCode auto_accept leaves the session asking for permission applyOptions committed the new flag before approving pending requests, so a failed reply left the session auto-approving while the stored option stayed off. The flag is restored when the apply throws. * fix(server): legacy Fast reaches draft discovery and saved profiles, and overlapping or replaced options keep the state they committed Draft controls and commands convert the config they hand to the provider, so inspecting a legacy Fast preference no longer fails Codex's strict options. A profile naming codex converts its saved fast_mode for the app's controls. OpenCode serializes auto_accept applies so a failed one restores exactly what it changed, and a replacement OMP runtime starts from the Fast the session opened with. * fix(server): an OMP replacement runtime that refuses the session's Fast publishes what it accepted The approval-mode restart installed the new runtime's state without comparing its Fast result to the session's, so a refusal never reached options_changed, the remembered value, or storage. The replacement now goes through the same comparison as refreshState. * fix(server): OMP turn completion publishes a Fast change, and Claude opens with Fast off on a model that has none OMP installed runtime state in several places and only one compared Fast; every state read from the runtime now goes through one install step. Claude kept a Fast default on a model without Fast, which made unrelated options reject until the user cleared it; the session now opens with Fast off and reports it in openOptionsPatch, as the model-switch path already does. * fix(server): a malformed Codex fast_mode is rejected, and profile options are renamed for clients by the agent manager's conversion convertLegacyOptions read any truthy fast_mode as Fast, so the string "false" ran priority. It now accepts only true, false or null. The profile store no longer renames keys: a literal codex profile was renamed in storage while an extends-codex profile was not. The config API now converts each profile's options with the manager's adapter-aware conversion, so codex and my-codex profiles read the same. * fix(server): a profile is stored in the current option keys, converted for the adapter its provider extends Profiles in config.json are old data entering, so the store converts them (stored value and incoming patch) with the same conversion the agent manager uses. Storage and clients now share one vocabulary: resetting a legacy Codex profile's speed removes what was shown, and a malformed fast_mode rejects the write instead of breaking later config reads. The config API goes back to copying the field shape only. The extends chain is followed by one function over either the registry's definitions or config.json's providers. * fix(server): profile options convert against the provider graph a write commits A write that edited a provider and a profile together folded the profile against a shallow merge that dropped the provider's extends, so its legacy Fast was not converted. The fold now sees the same deep-merged providers the write commits. * fix(server): draft speed shows the tier the first turn will run with Draft discovery reported the options as requested, so a Fast configured as a legacy fast_mode or the fast alias read as Normal while creating sent the model's own Fast tier. The draft now reports the options the scratch session opened with, as registration does. * fix(server): ACP option applies run one at a time Two overlapping applies shared one transaction guard, so when the first was refused after the agent had moved a select, its report was dropped as 'still in a transaction' and the second saw no difference. Applies are serialized, as OpenCode's are, so each reconciles against the state the previous one left. * fix(server): an ACP removal reports the choice the select lands on, and the Codex plan tests enable plan mode A removal asks the select for its empty choice and compared the result against that same empty choice, so applyOptions returned nothing and the manager stored the removal as null while the session ran the Default choice. The difference is now computed against what was asked (null), so the options hold the value the session runs with. The Codex plan-mode end-to-end tests called the removed session.setFeature through an optional call and silently skipped plan mode; they apply the option and fail loudly if the method is gone. The MCP parity wrapper forwards listControls instead of the removed listFeatures. * fix(server): plugin option applies run one at a time, and OpenCode reports the Auto Accept legacy full-access turns on Plugin sessions let two applyOptions overlap. The second finished and re-recorded the settings the plugin held, which included a change the first had already made and not yet reported; when the first then failed, nothing was left to report and the stored options kept the old value while the plugin ran the new one. Applies now queue on the session, the way the ACP adapter's do, so each reconciles against what the one before left. OpenCode normalizes the legacy full-access mode to build with Auto Accept on, but the session never said so, so the options the manager keeps did not hold Auto Accept and a reopen turned it off. The session now reports it through openOptionsPatch on create and resume. * refactor(server): openCodeOpenOptionsPatch takes one named-fields object * feat(app): the client and app work on options and controls The agent snapshot's `options` are the state and `controls` only draw them. Running and closed agents draw from the snapshot; drafts and profile forms ask `provider.controls.list.request` with their `providerOptions`, so aliases such as a legacy Fast profile's `service_tier: "fast"` are resolved once, by the daemon, and the draft keeps Fast highlighted. A draft adds only the user's edits and each provider's last-used control values; applying a profile seeds its non-control options (e.g. `sandbox_mode`) into the draft, and a profile form saves them back instead of pruning to the controls it can draw. A daemon without `server_info.features.providerOptionControls` still sends `features` and `featureValues`. `LegacyProviderOptions` in the client package is the one place that translates snapshots, draft listings, create and apply requests, and daemon-config profiles, so the app never branches on it. Persisted preferences and tab layouts rename `featureValues` through tagged COMPAT preprocessors. The features/controls bridge moves from the server into the protocol package so the client can reuse it. * fix(app): drafts and profile forms send every option layer to the daemon A cold create against a daemon without providerOptionControls routed control options (Claude fast_mode, Codex service_tier) as providerOptions, which that daemon does not read for them. The client now lists the provider's features before the first create or workspace create that carries options, so callers never prime a cache. Draft options moved into a plain model. Applying a profile replaces provider and options in one step, so the form's provider change that follows no longer clears a cross-provider profile's non-control options; choosing a provider by hand still starts over. The model sends its complete options (seed, last-used values once the provider says it still draws them, edits) to the daemon and the controls draw only the answer, so a remembered legacy fast is drawn as what it runs as. A toggle shows over the last answer until its own arrives. The profile form does the same: its edits go through resolution too. * fix(client): a legacy create routes its options from the controls of its own config Which options a legacy daemon exposes as features depends on the model, mode and thinking level, not only the provider: a Haiku snapshot with no features says nothing about Opus. The provider-keyed memory of control keys sent an Opus create's fast_mode as providerOptions, which that daemon does not read. A create that carries options now lists the controls for its own draft config and splits on that answer. The memory, and the snapshot and listing hooks that fed it, are gone. * fix(app): a closed agent shows its stored options, and a provider switch asks about its own options A closed agent's snapshot is projected from its stored record, which kept controls and provider options but dropped them from the payload, so the app drew no speed or other controls for it. The stored projection now carries them, with the legacy features derived from the same source. The draft read the form's provider and the model's options separately, so for the render after a manual provider change it asked the new provider about the previous provider's options. The request is now built from one snapshot of the model and is absent until the model has observed the new provider. * fix: persisted options keep their full shape, and every legacy snapshot gains controls Draft setups and form preferences validated option values as booleans, strings or null, but the options they now receive come from agents and profiles and can be objects, arrays or numbers. One such value failed validation and wiped the whole saved layout or the saved preferences. Both schemas now accept any JSON value. The legacy-daemon translation skipped the snapshots carried by agent_created, agent_resumed and timeline responses, so a created agent or a timeline refresh left the SDK handle without options and controls. The profile journey asserted the create request's options field; the wire field is providerOptions. * fix(client): a legacy profile with both featureValues and options keeps both A legacy daemon keeps an unknown `options` field on a profile it stored (profiles are passthrough), for example after a downgrade, while its own app keeps editing `featureValues`. Reading such a profile took `options` and dropped `featureValues`, so a Fast setting there was lost and the next save replaced it. Both are merged on read with an explicit `options` key winning, the same rule the daemon applies when it folds `featureValues`. The draft form input of draftControlsRequest is a named type. * fix(app): a draft stops sending a toggle the model in use does not offer A toggle made on one model stayed in the draft's edits after the form moved to a model whose controls do not include it, and was sent with the create. On a legacy daemon that key is not a feature for the new model, so it went out as a native provider option the daemon rejects. The draft now sends an edit only while the latest answer draws a control for it, and sends it again when a control for it returns. * fix(server): a closed agent's options include the provider defaults, like a live one's The stored snapshot projected only the options the agent owns, so an agent that ran with a config.json default (for example Claude fast_mode: true) showed the option as missing, and its legacy Fast control as off, until it was resumed. The projection takes the same resolver the live agent uses (the provider's defaults under the agent's own options). * fix(app): a draft keeps sending an option no control has drawn The previous change stopped sending any edit the latest answer drew no control for, which also dropped options set without a control (a plugin setting a token budget on the draft). Only an edit of a key an earlier answer for this draft drew as a control stops applying when a later answer draws none; every other edit always applies. * test(server): the MCP test agent manager resolves effective options * fix(app): a profile stops saving a toggle the model in use does not offer Switching a profile from Opus to Haiku kept the Fast edit, so the saved profile carried fast_mode that no control draws and an old daemon's provider rejects at create. The profile editor now drops a key an earlier answer drew as a control and the latest one does not, the rule the draft already follows; options no control ever drew are never touched. * fix(client): resetting an option on an old daemon writes the default it can take setAgentOptions({ service_tier: null }) sent a feature write with value null, which the old Codex setter rejects, leaving the paid Fast tier on. A toggle now resets to off and a choice to its default; an option with no control to name a default fails with the host-update message before anything is written. * fix(client): applying a config with a reset option on an old daemon writes the default it can take applyAgentConfig({ options: { service_tier: null } }) reached an old daemon as featureValues with null, which its Codex setter rejects. The config now takes the same translation as setAgentOptions: a toggle goes off, a choice goes to its default, and an option with no named default fails with the host-update message before anything is sent. * feat(plugin): provider plugins declare option controls and receive option changes A provider plugin reports `controls` and the `providerOptions` it runs in `session.config`, and receives running-session changes as `session.configure` `changes.providerOptions` (null returns a key to its default), under the same apply-or-throw contract as built-in providers. A control may declare a `defaultValue`; a value a plugin reports at that default for a key nobody set stays unset instead of being pinned to the agent. A plugin that still reports `settings` keeps working: the daemon reads each setting as a control plus an option and sends changes in both shapes (COMPAT(plugin-provider-settings)). The app resolves a control's icon as a Lucide name when it is not one of the built-in kebab-case names, so a plugin's icon shows live and in drafts. Public docs and the provider-direct example use only `providerOptions` and controls; the migration doc gains the rows. * fix(server): a plugin provider's reported options are stored like any provider's A control's `defaultValue` only says what the control shows for a key with no value. Opening and applying store every option the session reports, defaults and values nobody set included, as built-in providers do; the special case that left a value at the default unset is removed. * fix(server): a plugin decides which options it applies live A plugin reporting `controls` and `providerOptions` receives every key a live change touches, with or without a control, and applies them or rejects the whole request. The daemon's live-key guard now runs only for a plugin still reporting `settings`, which cannot refuse a key. * fix(server): a rewound plugin session reopens with its options as they stand The reopen merged the plugin's reported options over the launch record, so a key the plugin reset by leaving it out came back at its launch value. The session now keeps the committed options, removals included. The provider-direct example also refuses a combined request before changing anything. * fix(server): a plugin that stops reporting an option has reset it The adapter only visited keys present in a new report, so a key the plugin dropped to return to its default kept its stored value and its rewind value. A previously reported key that disappears is now reported as removed. * fix(server): an apply reports the options the plugin reset along the way Applying and unsolicited reports now share one conversion from the plugin's report to a patch, so a key the plugin stops reporting is a removal on both. * fix(server): an apply never reads a requested option as one the plugin dropped A plugin may run an option it never reports. Only a key it reported before can be reported as removed, and a rewind reopens with the accepted request plus what the plugin reported back. * test(server): an apply to a plugin that reports controls sends its changes as provider options * feat(plugins): agents and workspaces carry plugin metadata Plugins had nowhere to keep their own data on an agent or workspace, so Phase 5 and 6 surfaces would each have invented a side store. Both now hold an opaque Record<string, JsonValue> that Paseo stores, snapshots and hands to hooks without reading a key. Set at creation or changed with agent.metadata.update.request / workspace.metadata.update.request (top-level keys replace, null removes). Persisted on the agent and workspace records, so it survives a restart. Reaches agent.create.before (which may add to it), agent.open.before (read-only), agent.create.after and workspace.create.before/after. Gated once on server_info.features.entityMetadata; the client throws "Update the host" instead of sending to a host without it. * fix(plugins): an agent.open.before result may omit metadata The result schema required metadata, so a plugin written before metadata existed that returns its own object instead of spreading the request failed validation and the session open failed, even for agents with no metadata. An omitted metadata now means unchanged and is filled back in from the request so later plugins in the chain still see it; a present value that differs is still rejected. The restart test now sets metadata through the PaseoApi handles and checks that agent.open.before sees the patched value after the restart. * fix(plugins): omitted metadata in a hook result means unchanged An agent.create.before hook that returned its own { config, env } dropped metadata that an earlier hook in the chain had added, because only the caller's original metadata was restored at the end. The omitted field is now carried forward at each hook handoff, as agent.open.before already does. The agent.open.before result type also required metadata, so an older TypeScript plugin that returned its own object no longer compiled even though the daemon accepted it. The result type now makes it optional. * fix(plugins): omitted metadata in a workspace.create.before result means unchanged Same handoff as agent.create.before: a legacy hook that returned only { source, ... } dropped the caller's metadata and anything an earlier hook added, and workspace provisioning then defaulted it to {}. The omitted field is carried forward at each handoff; an explicit {} still replaces. * test(server): fixtures for agents and workspaces carry metadata Agent snapshots and workspace records now always carry metadata, so the hand-built fixtures and expectations in three existing suites name it. * docs(plugins): the hook result comment names metadata as the field that stays * fix(server): reopening a closed agent keeps metadata saved just before The loader reads the agent record, then queues a resume. A setMetadata queued ahead of that resume saves a newer record, and the open hooks saw it, but registration took metadata from the loader's older read and wrote it back over the saved patch. Registration now uses the metadata read inside the lifecycle lane. * docs(server): name the metadata gap when a handle-less agent is recreated on load * docs(server): the handle-less recreate gap spans the agent.create.before hook * docs(plugins): an agent.open.before hook starts writes to its own agent without awaiting An agent.open.before hook that awaits setMetadata (or any write) on the agent being opened deadlocks: the write joins the agent's lifecycle lane behind the open, and the open waits on the hook until it times out. The hooks reference now says so and shows the supported shape, a write started without awaiting, which runs right after the open. Deferred, not in this stack: reject such a write immediately instead of letting the hook time out. The host knows which plugin hook it is awaiting for the agent and which channel the write arrives on, so the rejection can be keyed on "this plugin is inside an open hook for this agent" without cross-process tagging, and an unrelated client's write would still wait as it does today. * feat(plugins): composer items and controls in all three composers A plugin registers a component with addComposerItem and reads and changes the composer through useComposer(): provider, model, mode, thinking, options, prompt, attachments and agent metadata. The agent, draft and New workspace composers provide the same ComposerInput and ComposerAgent halves, so a command reaches the right model without the plugin knowing which composer it sits in. Toggle, Select and Action are drawn by one ComposerControl renderer that the thinking select and provider option controls now use too. Controls sit in the toolbar when there is room and become rows in the existing overflow sheet otherwise, so on a phone they appear in the overflow. Plugin items count in the density presence so the composer condenses to make room. Model and mode stay specialized but share the trigger, density and overflow. Draft metadata is kept locally, sent at creation and reset when the prompt is sent. PluginAgentSnapshot.metadata, deferred from the metadata phase, lands here. The unused provider badge is removed. vitest resolves @floating-ui/react-native to its ESM build: the CJS entry requires the real react-native, whose Flow sources do not parse. * fix(plugins): composer commands run on current state, report failures, and reach the overflow sheet Draft commands read the state captured at render, so a plugin's `await setProvider(); await setModel()` acted on a stale provider. The draft form and options are now plain stores that commands read live, and `setProvider`/`setModel` reject an unavailable provider or a model the loaded catalog does not list. Draft `options` include the plugin's pending edits. Shared composer controls own the pending state and show a rejected command as an error toast, like the built-in controls. Callback payloads are objects (`{ value }`, `onPress(event)`) so they can grow without breaking plugins. The overflow sheet's content portals to the app root and lost the composer's agent, input, toast and query contexts, so plugin items drew nothing in it. `useComposerSheetBridge` carries them across. * test(plugins): composer commands tested on the models, overflow sheet in Playwright The draft composer's command rules (unavailable provider, unlisted model, edits belonging to the provider the form has now) moved from the React hooks into the form store and the draft options model. They take the host's catalog as a plain input, so the command tests run on the real models with no module mocks and no renderer. The overflow-sheet test faked the portal it was meant to verify. It is replaced by a Playwright spec that installs the composer-controls example and checks its rows in the narrow composer's Features sheet; it fails when the sheet's context bridge is removed. * test(plugins): lock draft option ownership without a subscription, name the overflow-sheet steps The draft option test subscribed the options model to the form, which in the app happens in a render effect, so it passed without the model observing the form's provider itself. A case with no subscription now fails when that observation is removed. The overflow-sheet spec reads as steps through a helper. * fix(plugins): composer option resets and model checks match the documented commands A draft kept `null` as an option value, so `setOptions({ key: null })` sent the null to the provider and creation failed. A null edit now removes the key from every draft layer, as the patch does on a running agent. A running agent's `setModel` accepted ids its catalog does not list; it now rejects them the way a draft does. The composer controls imported the toast host through the toast context, which pulled the host's animation module into every module that loads plugins. They use the API-only context instead. The migration guide's registration table gets the `addComposerItem` row its test requires. * fix(plugins): draft metadata survives a remount, plugin commands follow the composer lock Draft metadata was component state while the prompt lived in the draft store, so a composer that remounted across the compact breakpoint kept its text and lost the plugin's choices. It now lives in the draft store beside the prompt, is cleared when the draft is sent, and is not cleared when the prompt is emptied. It is not persisted across app restarts. While the New workspace composer is creating the agent, the built-in controls are disabled but plugin controls and commands were not. They read the composer's own lock: Paseo controls render disabled, and setPrompt, insertText and the agent commands refuse. The options and metadata a plugin reads are frozen copies, through the same helper the timeline projection uses. The composer control test mounted components in JSDOM, which the testing rules ban; it now runs in the browser project. * fix(plugins): a kept command honors the composer lock, and useAgent metadata is frozen A plugin action that awaits an RPC holds the composer it was created with. The lock was captured at that render, so a submit that started meanwhile did not stop its insertText. Commands now ask the composer whether it is locked when they run. The agent snapshot a plugin gets from useAgent froze only the outer metadata record. It now uses the same deep frozen copy as the composer. * fix(plugins): attachment commands honor the composer lock The creation request captures the attachments when it starts, so an attachment a plugin added or removed afterwards was lost or left in the request. They refuse like the prompt commands. * fix(plugins): a built-in select in the compact sheet keeps its action name The shared control named every icon-only select by its value ("Speed: Fast"), including in the compact sheet, where the row already shows the value. The sheet row is named by its action again ("Select speed"), as before the shared renderer. * test(app): composer item test installation carries the subscribe main added to InstalledPlugin Main's plugin streaming (#8527) made subscribe a required field of InstalledPlugin; the composer item model test builds its own installation and predates it. * feat(plugins): New workspace items set the branch and workspace metadata addNewWorkspaceItem mounts a plugin field on the New workspace screen, and useNewWorkspace() exposes host, project, isolation, base ref, branch and metadata with commands that follow the composer item rules: they act on the screen's state when they run, resolve once applied, reject while the screen is locked, and take JSON payloads. Host and project are read-only because a command that switched them would unmount the item that called it. The screen's pickable state (base selection, manual isolation, branch, metadata) moves into one plain store so pickers and plugin commands write to the same place; the screen reports derived facts to it on each render. The branch is sent as source.branchName only for a branch-off worktree, and metadata on workspace.create. Items render through ComposerControl with a new "field" surface (badge on desktop, full-width field when compact). Combobox ships here: Paseo owns the loading and error states, keeps previous results, and drops superseded searches. * fix(plugins): New workspace commands work from mount effects, and branch and base ref match what creation uses A command called from a New workspace item's mount effect rejected because the setup model only received its inputs and the pickers' handlers from a passive effect on the screen, which runs after a child's. The model now takes its inputs at construction, picks the base and isolation itself, and is refreshed in a layout effect; the screen supplies the side effects of a pick (the PR attachment, the remembered isolation) as listeners. The branch a plugin sets was dropped when no base was resolved, such as on a detached HEAD, because it was sent only for an explicit branch-off. It now applies whenever the worktree cuts a new branch, decided in one place that mirrors the daemon. baseRef.name was the display-shortened branch name, so setting back what was read based the worktree on the local branch instead of the origin one. It is now the exact ref creation uses, and host and baseRef are frozen like project and metadata. * fix(plugins): New workspace commands have the same effects as a pick, even from a mount effect The screen attached the pick side effects (remembering the isolation, syncing the picker's PR attachment) as listeners in its own useEffect, which runs after a child item's mount effect. A mount-time setIsolation("worktree") switched the screen but was not saved, and setBaseRef skipped the attachment sync. The effects are now injected when the setup model is built, so a command and a pick run the same code from the first render. Closing the picker stays in the picker's handler. * fix(plugins): a Combobox shows a failed refresh instead of the old results The query keeps its cached data when a reopened list fails to refresh, so the old items stayed selectable and the error never showed. A failed search now clears the list so its error shows. The migration guide maps addNewWorkspaceItem, which its registration-coverage test requires, and the superseded-search test waits on a later search instead of sleeping. * fix(plugins): a branch and metadata chosen for one project are not sent for another The setup model outlives the project and host it was chosen for, so an issue picked for project A was sent on workspace.create after the user switched to project B. The model now drops the branch and metadata when the project changes (project ids are host-scoped, so a host switch counts). A project that is still resolving is not a switch. The base selection is left alone: the built-in picker keeps a branch pick across a project switch, and that behavior is unchanged. * test(plugins): the project-switch spec expects the other project's metadata to be empty * fix(plugins): a host switch drops the branch and metadata even when the project id repeats A remote repository keeps the same project id on every host, so comparing the project id alone missed a switch from host A to host B for the same repository. The target is now the host and the project id together. * fix(server): a branch the caller named is not renamed from the first agent context The daemon marked every new branch-off worktree for automatic naming, recording the chosen branch as the placeholder, so the first agent's prompt could rename a branch a plugin or client had named through branchName. Only a branch the daemon derived from the worktree slug is a placeholder now. * fix(plugins): New workspace items remount when the project or host changes An item stayed mounted across a project switch, and its Combobox kept the previous project's results (same query key, cached data) selectable until the next search returned, so an issue from the old project could set the branch and metadata on the new one. A Combobox cannot detect that its inline search now means another project, so the item host keys the items by host and project id. Items and their search results start fresh for the new target, and a mount effect sets up again after the model clears the branch and metadata. * docs(plugins): a layout-effect command on mount also races the reset on a project switch * fix(plugins): a New workspace item's commands stop working once its project or host is left Every item received the same command functions, which act on the current screen state. A lookup that finished after the user switched projects could still call setBranch or setMetadata and overwrite the new project's choices; the reset on a switch only clears what was already written. The setup model now hands out commands per target with commandsFor({ serverId, projectId }). They reject with a "moved to another project or host" error when the screen is on another target, like the lock rejects, so the promise only resolves when the change took effect. * feat(plugins): reach a running agent's composer by reference useComposers(selector) in any plugin component and composers(selector) on every command context return the composer of a running agent, named by id or by focus, whether or not its tab is open. A running agent now has one store-backed composer model apart from any mounted tab. The mounted composer plugs its cursor-aware insert in while mounted; otherwise insertText and setPrompt write the agent's saved prompt. model and thinking resolve through the provider catalog with the picker's own function, so a read equals what the picker shows. The host reads one ComposerModel from context and no longer knows whether it is in an agent, a draft or New workspace. The daemon rejects an unlisted model or thinking option for a running agent, replacing the app-side guard. * fix(plugins): composers by reference follow the focused agent and reach retained composers - `{ focused: true }` is the agent Command Center hands to agent items, published by its registration through plugins/focused-agent.ts and empty outside a workspace. The composer source reads that module instead of the remembered workspace selection, the navigation store and the layout store, which also removes the require cycles those imports added. - A composer the app retains in a workspace the user left has no live input. `insertText` and `setPrompt` now store the text with `replaceDraftText`, which asks the mounted input to show it; before, the text reached the store but the retained input never displayed it. - `model` and `thinking` read exactly what the picker resolves before the catalog loads (no models), then re-resolve when it lands, instead of reading null. - The daemon validates a thinking option against the model the agent runs: the runtime model when the provider lists it, else the configured one. - The composer sources subscribe to query-cache updates only. A query another component creates during its render is announced as `added`, and a subscriber that updates then made React warn about updating a component while rendering a different one. A catalog read no longer starts its load synchronously either. * test(plugins): a Command Center agent item reaches the composer through the real client state The command-path test now reads workspace and agent through createPluginClientStateSource over seeded session stores, so an empty lookup, which makes the Command Center return before calling the item, would fail it. Also records at the focused-agent publisher that it publishes in an effect. * fix(plugins): a running agent's composer validates and refreshes against the agent's own catalog setAgentModel and setAgentThinkingOption checked the provider's global catalog, while the picker reads the catalog of the agent's directory, so a model only the project lists was rejected. The validation input now carries the directory. The composer read the catalog once with no observer, so reconnect repair, which refetches only active queries, never refreshed it and a failed load never retried. While anything watches, the composer now observes the catalog query. The shared composer map kept every agent's composer for the session. It is now dropped when nothing watches it and no composer is mounted. * fix(plugins): useComposers holds the composer it names, and a composer lives as long as its agent PluginComposersSource.subscribe watched the stores directly and never the composer model, so a component using useComposers did not keep the model's catalog observer alive and reconnect repair skipped it. subscribe now takes the selector and holds the model it names, following focus. Dropping a composer when it went idle left a command a plugin had saved calling a dead model after the tab reopened. A composer is now dropped when its agent leaves the session and nothing watches it or has one mounted. * fix(plugins): a composer refreshes a stale catalog on resumed demand, shares its store watches, and is released with its last holder Watching again, or reading once, after the catalog was invalidated or failed while nothing watched now starts one deduplicated refresh; the observer refetches on mount. Reconnect repair only refetches watched queries, so an unwatched catalog stayed stale. Each subscribe installed its own session and draft store callbacks, so N watchers received N squared notifications, including for other agents' drafts. One pair of subscriptions now serves all listeners, and the draft callback ignores drafts of other agents. A composer whose agent was removed while it was held was only released on the next session change. The last holder letting go now checks too, and an archived agent's idle composer is releasable. * test(server): live model and thinking switches use values the provider lists The daemon rejects a model or thinking option its provider does not list, so the live-preferences e2e can no longer switch to a made-up id. A provider that lists nothing to switch to skips the case. * test(server): the test providers list two models with thinking options, and the live switches run The fake providers listed one model and no thinking options, so once the daemon validated selections against the catalog the live model and thinking switches had nothing valid to switch to and skipped. Every fake provider now lists two models with thinking options, and the switches run for all three providers without depending on installed binaries. * fix(plugins): a retained composer that is not showing takes plugin writes through the draft On native a retained composer keeps its input mounted under display none, so the ref alone said the input was live and a plugin insertText replaced the stale selection instead of appending to the draft. The input is live only while its retained panel is showing. * test(plugins): the retained input liveness test runs in real Chromium * fix(plugins): a model or thinking change, an unreported option key, and a draft model reach the provider unchecked Paseo no longer checks these in front of the provider. A running agent's model or thinking change no longer waits for the catalog or checks it, a plugin provider is sent every option key and refuses what it cannot apply, and a draft setModel keeps the id as the model picker does. * fix(plugins): a plugin reporting settings is sent every key of an options patch * Run option, model, thinking and mode changes in the agent's lifecycle lane The agent manager owns all sequencing for one agent: applyOptions, setModel, setThinkingOption and setMode now run in the same lane as open, close, archive, labels and metadata, so a provider session never sees two of them at once. Provider-side serialization (the applying chains in the ACP, plugin and OpenCode sessions, and Claude's apply-over-current-options handling) is deleted. * Reopen a handleless agent inside its lifecycle lane A stored agent with no resumable session is now reopened by AgentManager.createAgentFromRecord, which rereads the record inside the agent's lane before creating the first session. A metadata or label write queued ahead is in the record it reads; one queued behind applies to the live agent. The loader no longer passes a record it read outside the lane. createAgent itself also runs in the lane, like resume. * Return the draft's options from AgentClient.listControls listControls now answers { controls, options } like AgentManager.listDraftControls: the options a session opened from the draft would run with, with config defaults merged in and anything the provider resolves natively for the ones nobody set. ACP fills unset feature selects from the probe session's currentValue, so a fresh Cursor draft shows the Fast selection the agent opens with instead of no selection. The legacy features response and the MCP draft listing already project from the manager's result, so they follow. * Send a profile's options on every write, empty included The profile form always sends options. The daemon reads a write without them as one from an app that predates options and folds featureValues over the stored ones; a write that carries them, empty included, replaces them. A profile left with no options is stored without the key, so removing the last one persists. * Read a remembered Codex fast_mode as its service tier The create-agent preferences convert the legacy key on read, keyed on the built-in codex provider id, so the Codex draft shows the Fast selection the user last used. Tagged COMPAT(featureValues) with the other legacy-option shims. * Document one option change at a time per agent The agent manager runs option, model, thinking and mode changes in the agent's lifecycle lane; providers do no sequencing. The hook deadlock warning now covers agent.create.before and option writes. * Flatten the profile fold's base selection and drop an unused import * Carry the New workspace context through portal hosts and the draft's metadata through retry * Convert legacy options when resolving a stored agent's effective options * Keep stored-record reads tolerant of a legacy option the conversion rejects * Keep plugin attachment items separate from the draft's own * Hand plugin command inputs to the host as its own copies
2026-11-09 09:54:40 +00:00 · 2026-11-09 10:10:16 +07:00
parent 8cc8e12007
commit 28c188513e
305 changed files with 17170 additions and 3347 deletions
@@ -49,22 +49,22 @@ Paseo only sees the returned promise, so detached work gets no error reporting a

 ## Hooks

-| Hook                      | Waits | Payload                                | Handler may change                             |
-| ------------------------- | ----- | -------------------------------------- | ---------------------------------------------- |
-| `workspace.create.before` | yes   | `{ request }`                          | Entire create request                          |
-| `workspace.create.after`  | no    | `{ workspace }`                        |                                                |
-| `workspace.archive.after` | no    | `{ workspace }`                        |                                                |
-| `worktree.create.before`  | yes   | `{ request }`                          | Creation options and destination               |
-| `worktree.create.after`   | yes   | `{ worktree }`                         | Files in the worktree; throw to abort creation |
-| `agent.create.before`     | yes   | `{ request: { config, env? } }`        | Saved config except `cwd`; `env`               |
-| `agent.create.after`      | no    | `{ agent }`                            |                                                |
-| `agent.open.before`       | yes   | `{ request }`                          | Launch-only `env`, `tools`, `mcpServers`       |
-| `agent.close.after`       | no    | `{ agent }`                            |                                                |
-| `agent.archive.after`     | no    | `{ agent, archivedAt }`                |                                                |
-| `agent.turn.before`       | no    | `{ agent, turnId }`                    |                                                |
-| `agent.turn.after`        | no    | `{ agent, turnId, outcome, timeline }` |                                                |
-| `agent.permission.before` | no    | `{ agent, request }`                   |                                                |
-| `agent.permission.after`  | no    | `{ agent, requestId, resolution }`     |                                                |
+| Hook                      | Waits | Payload                                   | Handler may change                             |
+| ------------------------- | ----- | ----------------------------------------- | ---------------------------------------------- |
+| `workspace.create.before` | yes   | `{ request }`                             | Entire create request                          |
+| `workspace.create.after`  | no    | `{ workspace }`                           |                                                |
+| `workspace.archive.after` | no    | `{ workspace }`                           |                                                |
+| `worktree.create.before`  | yes   | `{ request }`                             | Creation options and destination               |
+| `worktree.create.after`   | yes   | `{ worktree }`                            | Files in the worktree; throw to abort creation |
+| `agent.create.before`     | yes   | `{ request: { config, env?, metadata } }` | Saved config except `cwd`; `env`; `metadata`   |
+| `agent.create.after`      | no    | `{ agent }`                               |                                                |
+| `agent.open.before`       | yes   | `{ request }`                             | Launch-only `env`, `tools`, `mcpServers`       |
+| `agent.close.after`       | no    | `{ agent }`                               |                                                |
+| `agent.archive.after`     | no    | `{ agent, archivedAt }`                   |                                                |
+| `agent.turn.before`       | no    | `{ agent, turnId }`                       |                                                |
+| `agent.turn.after`        | no    | `{ agent, turnId, outcome, timeline }`    |                                                |
+| `agent.permission.before` | no    | `{ agent, request }`                      |                                                |
+| `agent.permission.after`  | no    | `{ agent, requestId, resolution }`        |                                                |

 ## Shared payloads

@@ -76,6 +76,7 @@ interface PluginHookAgent {
  provider: string;
  cwd: string;
  title: string | null;
+  metadata: Record<string, JsonValue>;
 }

 interface PluginHookWorkspace {
@@ -84,6 +85,7 @@ interface PluginHookWorkspace {
  cwd: string;
  name: string | null;
  archivedAt: string | null;
+  metadata: Record<string, JsonValue>;
 }

 type PluginTurnOutcome =
@@ -100,9 +102,29 @@ type PluginTurnOutcome =
 | `resolution` | SDK `AgentPermissionResponse`                                                          |
 | `archivedAt` | Timestamp string                                                                       |

+## Metadata
+
+Agents and workspaces carry a `metadata` record for plugin data. Keys are strings, values are any JSON value, and Paseo stores the record without reading a key. Prefix keys with your plugin id so plugins do not collide. Labels stay strings for filtering and tagging; use metadata for structured data.
+
+Set metadata when you create the agent or workspace, or change it later. `null` removes a key, and any other value replaces the key's whole value:
+
+```ts
+const agent = await paseo.agents.create({
+  config: { provider: "codex/gpt-5.5" },
+  cwd: "/projects/shop",
+  metadata: { "linear.issue": { id: "ENG-123" } },
+});
+
+agent.metadata; // { "linear.issue": { id: "ENG-123" } }
+await agent.setMetadata({ "linear.issue": null });
+await paseo.workspaces.ref(workspaceId).setMetadata({ "linear.issue": { id: "ENG-123" } });
+```
+
+Metadata survives a daemon restart. Every hook payload carries it: `workspace.create.before` and `agent.create.before` receive the metadata the caller sent, and the `after` hooks and `agent.open.before` receive what is stored. Against a host that predates metadata, these calls throw "Update the host to use metadata."
+
 ## workspace.create.before

-Receives `{ request }` with `source`, optional `title`, and `firstAgentContext`. You may replace the entire explicit create request; a throw, invalid result, or timeout fails creation. Existing workspaces and directory lookup/import are unaffected.
+Receives `{ request }` with `source`, optional `title`, optional `metadata`, and `firstAgentContext`. You may replace the entire explicit create request; a throw, invalid result, or timeout fails creation. Existing workspaces and directory lookup/import are unaffected.

 ### Choose workspace isolation

@@ -202,18 +224,18 @@ server.addHook("worktree.create.after", async ({ worktree }) => {

 ## agent.create.before

-Receives `{ request: { config, env? } }`. Config changes are saved and remain after the plugin is disabled or removed; `env` applies to the initial launch and is not saved. You cannot change `config.cwd`. A throw, invalid result, or timeout fails creation.
+Receives `{ request: { config, env?, metadata } }`. Config and `metadata` changes are saved and remain after the plugin is disabled or removed; `env` applies to the initial launch and is not saved. You cannot change `config.cwd`. A throw, invalid result, or timeout fails creation.

 **`agent.create.before.config`** uses `AgentSessionConfig`:

-| Fields                                        | Constraint                                                                 |
-| --------------------------------------------- | -------------------------------------------------------------------------- |
-| `provider`, `model`                           | Separate fields; changing provider may require changing model/mode/options |
-| `modeId`, `thinkingOptionId`, `featureValues` | Provider-specific selections                                               |
-| `title`, `systemPrompt`                       | Agent configuration                                                        |
-| `providerOptions`                             | Opaque provider-specific options                                           |
-| `mcpServers`, `toolPolicy`                    | MCP configuration and exact-tool preapprovals                              |
-| `cwd`                                         | Cannot change                                                              |
+| Fields                       | Constraint                                                                 |
+| ---------------------------- | -------------------------------------------------------------------------- |
+| `provider`, `model`          | Separate fields; changing provider may require changing model/mode/options |
+| `modeId`, `thinkingOptionId` | Provider-specific selections                                               |
+| `title`, `systemPrompt`      | Agent configuration                                                        |
+| `providerOptions`            | Provider options, including speed and auto-accept selections               |
+| `mcpServers`, `toolPolicy`   | MCP configuration and exact-tool preapprovals                              |
+| `cwd`                        | Cannot change                                                              |

 ### Change saved configuration

@@ -261,6 +283,17 @@ server.addHook("agent.create.after", async ({ agent }) => {

 Receives `{ request }`; only `env`, `tools`, and `mcpServers` may change, for this launch. All other fields are read-only. A throw, invalid result, or timeout fails the open.

+Do not await a write to the agent being opened: `setMetadata`, `setLabels`, or an option, model, thinking or mode change. The write waits for the open to finish, the open waits for your hook, so the hook times out and the open fails. Start the write without awaiting it; it runs right after the open:
+
+```ts
+server.addHook("agent.open.before", async ({ request }, { paseo }) => {
+  void paseo.agents
+    .ref(request.agentId)
+    .setMetadata({ "my.plugin": { openedBy: "hook" } })
+    .catch((error) => console.error(error));
+});
+```
+
 **`agent.open.before` request example:**

 ```json
@@ -271,6 +304,7 @@ Receives `{ request }`; only `env`, `tools`, and `mcpServers` may change, for th
  "cwd": "/projects/shop",
  "title": "Workspace notes",
  "labels": { "notes/enabled": "true" },
+  "metadata": { "linear.issue": { "id": "ENG-123" } },
  "tools": [],
  "mcpServers": {},
  "reason": "resume",
@@ -284,6 +318,7 @@ Receives `{ request }`; only `env`, `tools`, and `mcpServers` may change, for th
 | `workspaceId` | String or `null`                                                                                                        |
 | `title`       | Read-only string or `null`; creation title on create, stored title on resume.                                           |
 | `labels`      | Read-only string map; creation labels on create, stored labels on resume.                                               |
+| `metadata`    | Read-only JSON map; the [metadata](#metadata) stored on the agent.                                                      |
 | `tools`       | Editable `AgentToolDefinition[]`, local to this plugin. See [Attach tools to agents](#attach-tools-to-agents).          |
 | `mcpServers`  | Editable launch-only server map, local to this plugin. See [Inject MCP servers](#inject-mcp-servers).                   |
 | `reason`      | `create`, `resume`, `refresh`, `import`                                                                                 |
@@ -47,22 +47,22 @@ Paseo 只观察返回的 Promise，因此独立任务没有错误报告，也没

 ## 钩子一览 {#hooks}

-| 钩子                      | 等待 | 载荷                                   | 可修改                                    |
-| ------------------------- | ---- | -------------------------------------- | ----------------------------------------- |
-| `workspace.create.before` | 是   | `{ request }`                          | 整个创建请求                              |
-| `workspace.create.after`  | 否   | `{ workspace }`                        |                                           |
-| `workspace.archive.after` | 否   | `{ workspace }`                        |                                           |
-| `worktree.create.before`  | 是   | `{ request }`                          | 创建选项和目标路径                        |
-| `worktree.create.after`   | 是   | `{ worktree }`                         | worktree 中的文件；抛出错误中止创建       |
-| `agent.create.before`     | 是   | `{ request: { config, env? } }`        | 除 `cwd` 外的已保存配置；`env`            |
-| `agent.create.after`      | 否   | `{ agent }`                            |                                           |
-| `agent.open.before`       | 是   | `{ request }`                          | 仅用于启动的 `env`、`tools`、`mcpServers` |
-| `agent.close.after`       | 否   | `{ agent }`                            |                                           |
-| `agent.archive.after`     | 否   | `{ agent, archivedAt }`                |                                           |
-| `agent.turn.before`       | 否   | `{ agent, turnId }`                    |                                           |
-| `agent.turn.after`        | 否   | `{ agent, turnId, outcome, timeline }` |                                           |
-| `agent.permission.before` | 否   | `{ agent, request }`                   |                                           |
-| `agent.permission.after`  | 否   | `{ agent, requestId, resolution }`     |                                           |
+| 钩子                      | 等待 | 载荷                                      | 可修改                                     |
+| ------------------------- | ---- | ----------------------------------------- | ------------------------------------------ |
+| `workspace.create.before` | 是   | `{ request }`                             | 整个创建请求                               |
+| `workspace.create.after`  | 否   | `{ workspace }`                           |                                            |
+| `workspace.archive.after` | 否   | `{ workspace }`                           |                                            |
+| `worktree.create.before`  | 是   | `{ request }`                             | 创建选项和目标路径                         |
+| `worktree.create.after`   | 是   | `{ worktree }`                            | worktree 中的文件；抛出错误中止创建        |
+| `agent.create.before`     | 是   | `{ request: { config, env?, metadata } }` | 除 `cwd` 外的已保存配置；`env`；`metadata` |
+| `agent.create.after`      | 否   | `{ agent }`                               |                                            |
+| `agent.open.before`       | 是   | `{ request }`                             | 仅用于启动的 `env`、`tools`、`mcpServers`  |
+| `agent.close.after`       | 否   | `{ agent }`                               |                                            |
+| `agent.archive.after`     | 否   | `{ agent, archivedAt }`                   |                                            |
+| `agent.turn.before`       | 否   | `{ agent, turnId }`                       |                                            |
+| `agent.turn.after`        | 否   | `{ agent, turnId, outcome, timeline }`    |                                            |
+| `agent.permission.before` | 否   | `{ agent, request }`                      |                                            |
+| `agent.permission.after`  | 否   | `{ agent, requestId, resolution }`        |                                            |

 ## 共享载荷 {#shared-payloads}

@@ -74,6 +74,7 @@ interface PluginHookAgent {
  provider: string;
  cwd: string;
  title: string | null;
+  metadata: Record<string, JsonValue>;
 }

 interface PluginHookWorkspace {
@@ -82,6 +83,7 @@ interface PluginHookWorkspace {
  cwd: string;
  name: string | null;
  archivedAt: string | null;
+  metadata: Record<string, JsonValue>;
 }

 type PluginTurnOutcome =
@@ -98,9 +100,29 @@ type PluginTurnOutcome =
 | `resolution` | SDK 的 `AgentPermissionResponse`                                                         |
 | `archivedAt` | 时间戳字符串                                                                             |

+## 元数据 {#metadata}
+
+Agent 和工作区带有 `metadata` 记录，用于保存插件数据。键是字符串，值可以是任意 JSON 值，Paseo 只保存、不读取任何键。给键加上插件 ID 前缀，避免不同插件冲突。标签仍是用于筛选和标记的字符串；结构化数据请用元数据。
+
+可以在创建 Agent 或工作区时设置元数据，也可以之后修改。`null` 删除该键，其他值会替换该键的整个值：
+
+```ts
+const agent = await paseo.agents.create({
+  config: { provider: "codex/gpt-5.5" },
+  cwd: "/projects/shop",
+  metadata: { "linear.issue": { id: "ENG-123" } },
+});
+
+agent.metadata; // { "linear.issue": { id: "ENG-123" } }
+await agent.setMetadata({ "linear.issue": null });
+await paseo.workspaces.ref(workspaceId).setMetadata({ "linear.issue": { id: "ENG-123" } });
+```
+
+元数据在 daemon 重启后仍然保留。所有钩子载荷都带有元数据：`workspace.create.before` 和 `agent.create.before` 收到调用方发送的元数据，`after` 钩子和 `agent.open.before` 收到已保存的元数据。主机版本过旧时，这些调用会抛出 “Update the host to use metadata.”。
+
 ## workspace.create.before {#workspacecreatebefore}

-收到 `{ request }`，其中包含 `source`、可选的 `title` 和 `firstAgentContext`。可替换整个显式创建请求；抛出错误、无效返回或超时会让创建失败。已有工作区和目录查找、导入不受影响。
+收到 `{ request }`，其中包含 `source`、可选的 `title`、可选的 `metadata` 和 `firstAgentContext`。可替换整个显式创建请求；抛出错误、无效返回或超时会让创建失败。已有工作区和目录查找、导入不受影响。

 ### 选择工作区隔离方式 {#choose-workspace-isolation}

@@ -199,18 +221,18 @@ server.addHook("worktree.create.after", async ({ worktree }) => {

 ## agent.create.before {#agentcreatebefore}

-收到 `{ request: { config, env? } }`。配置修改会保存，即使插件以后被停用或移除；`env` 只用于首次启动，不会保存。不能修改 `config.cwd`。抛出错误、无效返回或超时会让创建失败。
+收到 `{ request: { config, env?, metadata } }`。配置和 `metadata` 的修改会保存，即使插件以后被停用或移除；`env` 只用于首次启动，不会保存。不能修改 `config.cwd`。抛出错误、无效返回或超时会让创建失败。

 **`agent.create.before.config`** 使用 `AgentSessionConfig`：

-| 字段                                          | 约束                                                     |
-| --------------------------------------------- | -------------------------------------------------------- |
-| `provider`, `model`                           | 独立的字段；修改 Provider 可能需要同时修改模型/模式/选项 |
-| `modeId`, `thinkingOptionId`, `featureValues` | 特定于 Provider 的选择                                   |
-| `title`, `systemPrompt`                       | Agent 配置                                               |
-| `providerOptions`                             | 不透明的、特定于 Provider 的选项                         |
-| `mcpServers`, `toolPolicy`                    | MCP 配置和精确的工具预批准                               |
-| `cwd`                                         | 不能修改                                                 |
+| 字段                         | 约束                                                     |
+| ---------------------------- | -------------------------------------------------------- |
+| `provider`, `model`          | 独立的字段；修改 Provider 可能需要同时修改模型/模式/选项 |
+| `modeId`, `thinkingOptionId` | 特定于 Provider 的选择                                   |
+| `title`, `systemPrompt`      | Agent 配置                                               |
+| `providerOptions`            | Provider 选项，包括速度和自动批准的选择                  |
+| `mcpServers`, `toolPolicy`   | MCP 配置和精确的工具预批准                               |
+| `cwd`                        | 不能修改                                                 |

 ### 修改已保存的配置 {#change-saved-configuration}

@@ -257,6 +279,17 @@ server.addHook("agent.create.after", async ({ agent }) => {

 收到 `{ request }`，只能修改 `env`、`tools` 和 `mcpServers`，修改只用于此次启动。其他字段只读。抛出错误、无效返回或超时会让打开操作失败。

+不要 await 对正在打开的 Agent 的写入，例如 `setMetadata`。该写入要等打开完成，而打开在等你的钩子，结果钩子超时，打开失败。启动写入但不要 await，它会在打开完成后立即执行：
+
+```ts
+server.addHook("agent.open.before", async ({ request }, { paseo }) => {
+  void paseo.agents
+    .ref(request.agentId)
+    .setMetadata({ "my.plugin": { openedBy: "hook" } })
+    .catch((error) => console.error(error));
+});
+```
+
 **`agent.open.before` 请求示例：**

 ```json
@@ -267,6 +300,7 @@ server.addHook("agent.create.after", async ({ agent }) => {
  "cwd": "/projects/shop",
  "title": "Workspace notes",
  "labels": { "notes/enabled": "true" },
+  "metadata": { "linear.issue": { "id": "ENG-123" } },
  "tools": [],
  "mcpServers": {},
  "reason": "resume",
@@ -280,6 +314,7 @@ server.addHook("agent.create.after", async ({ agent }) => {
 | `workspaceId` | 字符串或 `null`                                                                                          |
 | `title`       | 只读字符串或 `null`；创建时使用创建请求的标题，恢复时使用已保存的标题。                                  |
 | `labels`      | 只读的字符串映射；创建时使用创建请求的标签，恢复时使用已保存的标签。                                     |
+| `metadata`    | 只读的 JSON 映射；Agent 上已保存的[元数据](#metadata)。                                                  |
 | `tools`       | 可编辑的 `AgentToolDefinition[]`，仅包含此插件的工具。参阅[为 Agent 附加工具](#attach-tools-to-agents)。 |
 | `mcpServers`  | 可编辑的服务器映射，仅用于启动且仅包含本插件的条目。参阅[注入 MCP 服务器](#inject-mcp-servers)。         |
 | `reason`      | `create`、`resume`、`refresh`、`import`                                                                  |
@@ -14,6 +14,8 @@ A plugin is a TypeScript project installed into one Paseo daemon. It can add
 [file panels](/docs/plugins/reference#file-panels),
 [Command Center items](/docs/plugins/reference#command-center-items),
 [slash commands](/docs/plugins/reference#slash-commands),
+[composer items](/docs/plugins/reference#composer-items),
+[New workspace items](/docs/plugins/reference#new-workspace-items),
 [composer pills](/docs/plugins/reference#composer-pills),
 [timeline items](/docs/plugins/reference#timeline-items),
 [themes](/docs/plugins/reference#contribute-a-theme),
@@ -6,7 +6,7 @@ nav: 快速上手

 # 插件快速上手 {#plugin-quickstart}

-插件是安装到某个 Paseo daemon 中的 TypeScript 项目。它可以添加[界面和侧边栏项](/docs/plugins/reference#screens-and-sidebar-items)、[工作区面板](/docs/plugins/reference#workspace-panels)、[文件面板](/docs/plugins/reference#file-panels)、[Command Center 项](/docs/plugins/reference#command-center-items)、[斜杠命令](/docs/plugins/reference#slash-commands)、[Composer 标签](/docs/plugins/reference#composer-pills)、[时间线条目](/docs/plugins/reference#timeline-items)、[主题](/docs/plugins/reference#contribute-a-theme)、[附件来源](/docs/plugins/reference#add-a-composer-attachment-source)和 [daemon 端 RPC](/docs/plugins/reference#add-plugin-specific-backend-behavior)。它还可以[把编程 Agent 接入为 Provider](/docs/plugins/providers)。客户端贡献会在连接到该 daemon 的每个 Paseo 客户端上运行，包括移动端。
+插件是安装到某个 Paseo daemon 中的 TypeScript 项目。它可以添加[界面和侧边栏项](/docs/plugins/reference#screens-and-sidebar-items)、[工作区面板](/docs/plugins/reference#workspace-panels)、[文件面板](/docs/plugins/reference#file-panels)、[Command Center 项](/docs/plugins/reference#command-center-items)、[斜杠命令](/docs/plugins/reference#slash-commands)、[Composer 项](/docs/plugins/reference#composer-items)、[新建工作区项](/docs/plugins/reference#new-workspace-items)、[Composer 标签](/docs/plugins/reference#composer-pills)、[时间线条目](/docs/plugins/reference#timeline-items)、[主题](/docs/plugins/reference#contribute-a-theme)、[附件来源](/docs/plugins/reference#add-a-composer-attachment-source)和 [daemon 端 RPC](/docs/plugins/reference#add-plugin-specific-backend-behavior)。它还可以[把编程 Agent 接入为 Provider](/docs/plugins/providers)。客户端贡献会在连接到该 daemon 的每个 Paseo 客户端上运行，包括移动端。

 浏览[已发布的插件](https://paseo.sh/plugins)，然后在你的 daemon 上安装一个：

@@ -81,6 +81,8 @@ Use this table as the complete registration checklist.
 | `plugin.addClientSlashCommand(command)` in the old root entry                                 | `client.addSlashCommand(command)` in `index.client.tsx`                                                                     |
 | `plugin.addClientSide(fn)` in the old root entry                                              | Delete the wrapper and move the body of `fn` into the default client entry function                                         |
 | `client.addComposerPill(pill)` inside the old client callback                                 | `client.addComposerPill(pill)` inside `index.client.tsx` or an imported `client/` function                                  |
+| New composer item contribution                                                                | `client.addComposerItem(item)` in `index.client.tsx`; see [composer items](reference#composer-items)                        |
+| New New workspace item contribution                                                           | `client.addNewWorkspaceItem(item)` in `index.client.tsx`; see [New workspace items](reference#new-workspace-items)          |
 | New header contribution                                                                       | `client.addHeaderButton({ id, workspaceId, button })`                                                                       |
 | `plugin.addAttachmentSource(source)` in the old root entry                                    | `client.addAttachmentSource(source)` in `index.client.tsx`                                                                  |
 | New settings screen contribution                                                              | `client.addSettingsScreen(screen)` in `index.client.tsx`; see [settings screens](reference#settings-screens)                |
@@ -185,6 +187,26 @@ For paced timeline text, replace `useRevealedText(text, phase)` and the surround
 `<StreamedText text={text} phase={phase} style={style} />` from `/client/ui`.
 Use `SettingsSection` for plugin settings headings; `SettingsGroup` is deprecated.

+### Provider options in v0.15
+
+A provider plugin has one configuration record, `providerOptions`, and describes which keys get a
+composer control. A provider that still reports `settings` keeps working through v0.15: Paseo reads each
+setting `id` as an option key and each `value` as that option, and sends changes in both
+`changes.providerOptions` and `changes.settings`. Remove `settings` before the shim is deleted after
+2027-05-01.
+
+| Previous API                                   | Replacement                                                                |
+| ---------------------------------------------- | -------------------------------------------------------------------------- |
+| `session.config` `settings: ProviderSetting[]` | `controls: ProviderOptionControl[]` plus `providerOptions`                 |
+| Setting `id`                                   | Control `key`                                                              |
+| Setting `value`                                | `providerOptions[key]`; the control holds no value                         |
+| Select setting `options: { label, value }[]`   | Select control `choices: { value, label, description? }[]`                 |
+| Setting with no icon or default                | Control `icon` (a Lucide name) and `defaultValue`                          |
+| `session.configure` `changes.settings`         | `changes.providerOptions`; `null` returns a key to its default             |
+| `session.open` `config.settings`               | `config.providerOptions`                                                   |
+| `ProviderSetting` type                         | `ProviderOptionControl`                                                    |
+| `agent.create.before` `config.featureValues`   | `config.providerOptions`; a returned `featureValues` edit is still applied |
+
 ## 5. Recognize half-migration errors

 | Compiler or load error                                                                                                     | Meaning and fix                                                                                                           |
@@ -73,6 +73,8 @@ my-plugin/
 | 旧根入口中的 `plugin.addClientSlashCommand(command)`                                          | `index.client.tsx` 中的 `client.addSlashCommand(command)`                                                              |
 | 旧根入口中的 `plugin.addClientSide(fn)`                                                       | 删除这层包装，把 `fn` 的函数体移入默认的客户端入口函数                                                                 |
 | 旧客户端回调中的 `client.addComposerPill(pill)`                                               | `index.client.tsx` 或被导入的 `client/` 函数中的 `client.addComposerPill(pill)`                                        |
+| 新的编辑器项贡献                                                                              | `index.client.tsx` 中的 `client.addComposerItem(item)`;见[编辑器项](reference#composer-items)                          |
+| 新的“新建工作区”项贡献                                                                        | `index.client.tsx` 中的 `client.addNewWorkspaceItem(item)`;见[新建工作区项](reference#new-workspace-items)             |
 | 新的标题栏贡献                                                                                | `client.addHeaderButton({ id, workspaceId, button })`                                                                  |
 | 旧根入口中的 `plugin.addAttachmentSource(source)`                                             | `index.client.tsx` 中的 `client.addAttachmentSource(source)`                                                           |
 | 新的设置界面贡献                                                                              | `index.client.tsx` 中的 `client.addSettingsScreen(screen)`；见[设置界面](reference#settings-screens)                   |
@@ -152,6 +154,22 @@ pill.remove();

 对于逐步显示的时间线文本，把 `useRevealedText(text, phase)` 及其外层的 `Text` 换成 `/client/ui` 中的 `<StreamedText text={text} phase={phase} style={style} />`。插件设置的标题使用 `SettingsSection`；`SettingsGroup` 已弃用。

+### v0.15 中的 Provider 选项 {#provider-options-in-v015}
+
+Provider 插件只有一个配置记录 `providerOptions`，并用控件描述哪些键显示在 Composer 中。仍然报告 `settings` 的 Provider 在 v0.15 中继续可用：Paseo 把每个 setting 的 `id` 当作选项键，把 `value` 当作该选项的值，并同时在 `changes.providerOptions` 和 `changes.settings` 中发送修改。请在 2027-05-01 之后兼容层被删除之前移除 `settings`。
+
+| 之前的 API                                        | 替代方式                                                        |
+| ------------------------------------------------- | --------------------------------------------------------------- |
+| `session.config` 的 `settings: ProviderSetting[]` | `controls: ProviderOptionControl[]` 加 `providerOptions`        |
+| Setting 的 `id`                                   | 控件的 `key`                                                    |
+| Setting 的 `value`                                | `providerOptions[key]`；控件本身不保存值                        |
+| 选择类 setting 的 `options: { label, value }[]`   | 选择类控件的 `choices: { value, label, description? }[]`        |
+| 没有图标或默认值的 setting                        | 控件的 `icon`（Lucide 名称）和 `defaultValue`                   |
+| `session.configure` 的 `changes.settings`         | `changes.providerOptions`；`null` 表示恢复该键的默认值          |
+| `session.open` 的 `config.settings`               | `config.providerOptions`                                        |
+| `ProviderSetting` 类型                            | `ProviderOptionControl`                                         |
+| `agent.create.before` 的 `config.featureValues`   | `config.providerOptions`；返回的 `featureValues` 修改仍会被应用 |
+
 ## 5. 识别只迁移了一半的错误 {#5-recognize-half-migration-errors}

 | 编译器或加载错误                                                                                                           | 含义与修复方法                                                                                     |
@@ -22,7 +22,7 @@ Choose one implementation path:

 The examples are:

- [`provider-direct`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/provider-direct): sessions, settings, prompts, persistence, child sessions, and a provider-owned timeline renderer;
+- [`provider-direct`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/provider-direct): sessions, option controls, prompts, persistence, child sessions, and a provider-owned timeline renderer;
 - [`provider-acp-transformer`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/provider-acp-transformer): an ACP command template with a Zod-validated vendor edit transformer. Replace `example-acp --stdio` with an installed ACP agent before loading it;
 - [`inline-thinking`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/inline-thinking): a renderer-only plugin that does not implement a provider.

@@ -138,7 +138,7 @@ later through `session.config`.
 ## Open a session

 `session.open` contains the complete launch configuration: working directory, environment, system
-prompt, MCP servers, tool policy, model, mode, settings, opaque provider options, and persistence
+prompt, MCP servers, tool policy, model, mode, `providerOptions`, and persistence
 preference.

 For persisted host-scoped plugin settings, use the handle returned by `server.registerSettings()`.
@@ -177,7 +177,8 @@ emit({
    models,
    modes,
    thinkingOptions,
-    settings: [],
+    controls: [],
+    providerOptions: {},
  },
 });
 emit({ type: "session.ready", requestId: input.requestId, sessionId: input.sessionId });
@@ -229,10 +230,16 @@ terminal `completed`, `failed`, or `canceled` event.
 At this point the provider is usable: users can select a model, open a session, send a message, and
 see the response.

-## Add session-specific composer controls
+## Add composer controls for provider options

-Add `session.configure` only when the native agent has settings users should change after opening a
-session. Publish them in `session.config` as toggle or select controls:
+`providerOptions` is the provider's own configuration: one record of JSON values that Paseo
+stores per agent and hands to `session.open`. It includes the defaults a user set in `config.json`
+for your provider. Validate every key you read.
+
+Add `controls` only when users should see and change some of those options in the composer. A
+control draws one top-level key of `providerOptions` as a toggle or a select. It holds no value:
+Paseo reads the value from `providerOptions`. Publish the controls and the values you run with in
+`session.config`:

 ```ts
 emit({
@@ -243,35 +250,48 @@ emit({
    models: [{ id: "agent-large", label: "Agent Large" }],
    modes: [],
    thinkingOptions: [],
-    settings: [
-      {
-        type: "toggle",
-        id: "fast",
-        label: "Fast mode",
-        value: nativeSession.fast,
-      },
+    controls: [
+      { type: "toggle", key: "fast", label: "Fast mode", icon: "Zap", defaultValue: false },
      {
        type: "select",
-        id: "approval",
+        key: "approval",
        label: "Approvals",
-        value: nativeSession.approval,
-        options: [
-          { label: "Ask", value: "ask" },
-          { label: "Auto accept", value: "auto" },
+        icon: "Shield",
+        defaultValue: "ask",
+        choices: [
+          { value: "ask", label: "Ask" },
+          { value: "auto", label: "Auto accept" },
        ],
      },
    ],
+    providerOptions: { fast: nativeSession.fast, approval: nativeSession.approval },
  },
 });
 ```

-Paseo renders these controls in the composer. A user change arrives as `session.configure`; apply it
-and publish the committed `session.config` before `request.completed`. The provider may change the
-available controls at runtime, including after a model change.
+`icon` is a Lucide icon name. `defaultValue` is what a control shows for a key that has no value.
+Paseo stores every value you report when a session opens or a change is applied, including values
+at the default and values nobody set. The same controls appear in the New workspace screen, in draft
+tabs, and on running agents. Offer a control only for a key you can change on a running session.
+The provider may change its controls at runtime, including after a model change.

-`settings` are user-facing controls. `providerOptions` is opaque JSON supplied at session creation
-for provider-specific configuration that Paseo does not render. A provider-specific token budget
-belongs in one of those two places; it is not a dedicated prompt field.
+A change arrives as `session.configure` with `changes.providerOptions` holding only the keys
+that changed, whether or not they have a control. Apply every key and publish the committed
+`session.config` before `request.completed`. Fail the request with `request.failed` and leave
+every key as it was when you cannot apply one, for example a key you read only when a session
+opens. A
+value of `null` returns that key to the provider's default. Publish what the session ended up
+with, not a copy of the request: Paseo stores your published values so the stored options match
+what runs.
+
+If the provider changes an option on its own, for example a model switch turns Fast off, publish
+a new `session.config` with the new values. Paseo stores them and does not set the old ones
+back.
+
+Not every option needs a control. A provider-specific token budget, for example, belongs in
+`providerOptions` and is not a dedicated prompt field. It is delivered in `session.open`, a caller
+can change it on a running agent, and your `session.configure` handler decides whether it can
+apply it live. Report it in `providerOptions` so Paseo stores what runs.

 ## Add persistence and replay

@@ -467,7 +487,7 @@ export const vendorEdits: AcpTransformer = {
 Test the provider against the real agent, not only mocked frames:

 1. install the plugin as a directory source;
-2. confirm its SVG, models, modes, and settings appear;
+2. confirm its SVG, models, modes, and option controls appear;
 3. create a session and complete a real prompt;
 4. exercise permissions, steering, cancellation, persistence, and replay when supported;
 5. render every custom timeline item on desktop and mobile-width layouts;
@@ -19,7 +19,7 @@ Provider 插件把一个编程 Agent 接入 Paseo，而无需把它加入 Paseo

 示例有：

- [`provider-direct`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/provider-direct)：会话、设置、提示词、持久化、子会话，以及一个由 Provider 拥有的时间线渲染器；
+- [`provider-direct`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/provider-direct)：会话、选项控件、提示词、持久化、子会话，以及一个由 Provider 拥有的时间线渲染器；
 - [`provider-acp-transformer`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/provider-acp-transformer)：一个 ACP 命令模板，带有一个用 Zod 校验的厂商编辑转换器。加载之前，请把 `example-acp --stdio` 替换为一个已安装的 ACP Agent；
 - [`inline-thinking`](https://github.com/getpaseo/paseo/tree/main/plugin-examples/inline-thinking)：一个只包含渲染器、不实现 Provider 的插件。

@@ -125,7 +125,7 @@ if (input.type === "catalog") {

 ## 打开会话 {#open-a-session}

-`session.open` 包含完整的启动配置：工作目录、环境变量、系统提示词、MCP 服务器、工具策略、模型、模式、设置、不透明的 Provider 选项以及持久化偏好。
+`session.open` 包含完整的启动配置：工作目录、环境变量、系统提示词、MCP 服务器、工具策略、模型、模式、`providerOptions` 以及持久化偏好。

 对于持久化的、作用于主机的插件设置，请使用 `server.registerSettings()` 返回的句柄。在目录和会话回调中读取它；当 Provider 在内存中保留配置时，订阅它。`read()` 和 `subscribe()` 的契约见[设置](./reference.md#persisted-values)。

@@ -160,7 +160,8 @@ emit({
    models,
    modes,
    thinkingOptions,
-    settings: [],
+    controls: [],
+    providerOptions: {},
  },
 });
 emit({ type: "session.ready", requestId: input.requestId, sessionId: input.sessionId });
@@ -207,9 +208,11 @@ emit({ type: "session.turn", sessionId, turnId, state: "completed" });

 到这一步，Provider 已经可用：用户可以选择模型、打开会话、发送消息并看到回复。

-## 添加会话专属的 Composer 控件 {#add-session-specific-composer-controls}
+## 为 Provider 选项添加 Composer 控件 {#add-composer-controls-for-provider-options}

-只有当原生 Agent 有用户在打开会话后需要修改的设置时，才添加 `session.configure`。在 `session.config` 中以开关或选择控件的形式发布它们：
+`providerOptions` 是 Provider 自己的配置：一个由 JSON 值组成的记录，Paseo 按 Agent 保存它，并在 `session.open` 中交给你。它包含用户在 `config.json` 中为你的 Provider 设置的默认值。请校验你读取的每个键。
+
+只有当用户需要在 Composer 中查看并修改其中一部分选项时，才添加 `controls`。一个控件把 `providerOptions` 的一个顶层键绘制为开关或选择器。控件本身不保存值：Paseo 从 `providerOptions` 读取值。在 `session.config` 中发布控件，以及你正在使用的值：

 ```ts
 emit({
@@ -220,31 +223,32 @@ emit({
    models: [{ id: "agent-large", label: "Agent Large" }],
    modes: [],
    thinkingOptions: [],
-    settings: [
-      {
-        type: "toggle",
-        id: "fast",
-        label: "Fast mode",
-        value: nativeSession.fast,
-      },
+    controls: [
+      { type: "toggle", key: "fast", label: "Fast mode", icon: "Zap", defaultValue: false },
      {
        type: "select",
-        id: "approval",
+        key: "approval",
        label: "Approvals",
-        value: nativeSession.approval,
-        options: [
-          { label: "Ask", value: "ask" },
-          { label: "Auto accept", value: "auto" },
+        icon: "Shield",
+        defaultValue: "ask",
+        choices: [
+          { value: "ask", label: "Ask" },
+          { value: "auto", label: "Auto accept" },
        ],
      },
    ],
+    providerOptions: { fast: nativeSession.fast, approval: nativeSession.approval },
  },
 });
 ```

-Paseo 会在 Composer 中渲染这些控件。用户的修改会以 `session.configure` 的形式到达；应用它，并在 `request.completed` 之前发布已确定的 `session.config`。Provider 可以在运行时改变可用的控件，包括在模型变化之后。
+`icon` 是 Lucide 图标名称。`defaultValue` 是控件在键没有值时显示的值。会话打开或应用修改时，你报告的每个值（包括处于默认值的值和无人设置过的值）Paseo 都会保存。相同的控件会出现在“新建工作区”界面、草稿标签页和运行中的 Agent 上。只为你能在运行中的会话里修改的键提供控件。Provider 可以在运行时改变控件，包括在模型变化之后。

-`settings` 是面向用户的控件。`providerOptions` 是在创建会话时提供的不透明 JSON，用于 Paseo 不会渲染的 Provider 专属配置。Provider 专属的 token 预算应放在这两处之一；它不是一个专门的提示词字段。
+修改会以 `session.configure` 的形式到达，`changes.providerOptions` 只包含发生变化的键，无论这些键是否有控件。应用每一个键，并在 `request.completed` 之前发布已确定的 `session.config`。如果无法应用其中某个键（例如只在会话打开时读取的键），用 `request.failed` 使请求失败，并让每个键保持原样。值为 `null` 表示把该键恢复为 Provider 的默认值。请发布会话最终实际使用的值，而不是请求的副本：Paseo 会保存你发布的值，使保存的选项与实际运行的一致。
+
+如果 Provider 自行改变了某个选项（例如切换模型后关闭了 Fast），请发布带有新值的 `session.config`。Paseo 会保存它们，不会把旧值设置回去。
+
+并非每个选项都需要控件。例如 Provider 专属的 token 预算应放在 `providerOptions` 中，它不是一个专门的提示词字段。它会在 `session.open` 中交付，调用方可以在运行中的 Agent 上修改它，由你的 `session.configure` 处理程序决定能否实时应用。请在 `providerOptions` 中报告它，使 Paseo 保存实际运行的值。

 ## 添加持久化与重放 {#add-persistence-and-replay}

@@ -405,7 +409,7 @@ export const vendorEdits: AcpTransformer = {
 用真实的 Agent 测试 Provider，而不只是模拟的数据帧：

 1. 以目录来源安装插件；
-2. 确认它的 SVG、模型、模式和设置都会显示；
+2. 确认它的 SVG、模型、模式和选项控件都会显示；
 3. 创建会话并完成一段真实的提示词；
 4. 在支持的情况下，试用权限、引导、取消、持久化和重放；
 5. 在桌面和移动端宽度的布局中渲染每一种自定义时间线条目；
@@ -409,7 +409,7 @@ process, credential, and other machine-local work under `server/`. A plugin with
 ### Providers

 Follow [Build a provider plugin](/docs/plugins/providers) for direct and ACP implementations,
-session lifecycle, composer settings, timeline renderers, testing, and distribution.
+session lifecycle, option controls, timeline renderers, testing, and distribution.

 Call `server.registerProvider()` with a `ProviderRegistration` from
 `@getpaseo/plugin/server/provider`. Its connection accepts inputs with `send()` and emits complete state
@@ -420,10 +420,12 @@ Use the single `session.prompt` input for messages, structured commands, steerin
 effects. Repeat `clientMessageId` on the live user timeline item and publish exactly one matching
 `session.prompt_result`. Publish provider-created children as sessions with `parentSessionId`.

-Provider settings are toggle/select descriptors that Paseo renders in the composer. Keep
-provider-private options under `ProviderSessionConfig.providerOptions` on `session.open`.
-This record includes configured defaults and per-agent overrides; validate and apply it in your
-provider. See [Provider options](/docs/sdk/provider-options) for configuration and merge semantics.
+Provider options are one record, `ProviderSessionConfig.providerOptions` on `session.open`. It
+includes configured defaults and per-agent overrides; validate and apply it in your provider. Report
+`controls` in `session.config` for the top-level keys that get a toggle or select in the composer,
+with the values the session runs under `providerOptions`. A running-session change arrives as
+`session.configure` with `changes.providerOptions`. See [Provider options](/docs/sdk/provider-options)
+for configuration and merge semantics.
 Host tools arrive as MCP servers in the complete
 session config.

@@ -1902,6 +1904,231 @@ header has no room for plugin buttons, so each one is a row of the workspace men
 icon and title; its menus and popovers open as pages of that sheet. Placement and overflow are host
 decisions.

+## Composer items
+
+`client.addComposerItem({ id, Component })` puts a component in the composer: the agent composer,
+the draft composer for a new agent, and the composer on the New workspace screen. `useComposer()`
+reads and changes what the composer configures, and `Toggle`, `Select` and `Action` from
+`@getpaseo/plugin/client/ui` draw the controls.
+
+```tsx
+import { useComposer, type PluginClientContext } from "@getpaseo/plugin/client";
+import { Action, Select, Toggle } from "@getpaseo/plugin/client/ui";
+
+function ReviewFlag() {
+  const composer = useComposer();
+  return (
+    <Toggle
+      title="Needs review"
+      icon="Flag"
+      value={composer.agent.metadata["review.needsReview"] === true}
+      onValueChange={({ value }) =>
+        composer.setMetadata({ "review.needsReview": value ? true : null })
+      }
+    />
+  );
+}
+
+function Checklist() {
+  const composer = useComposer();
+  return (
+    <Action
+      title="Insert checklist"
+      icon="ListChecks"
+      onPress={() => composer.insertText("- [ ] Tests\n- [ ] Docs\n")}
+    />
+  );
+}
+
+export default function contribute(client: PluginClientContext) {
+  client.addComposerItem({ id: "review-flag", Component: ReviewFlag });
+  client.addComposerItem({ id: "checklist", Component: Checklist });
+  return () => {};
+}
+```
+
+`useComposer()` returns the composer the item sits in:
+
+| Field or command                                    | Meaning                                                                                                                                                                                                                                                                                                   |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `context`                                           | `"agent"` for a running agent, `"draft"` for a new agent in a workspace, `"new-workspace"` for the New workspace screen.                                                                                                                                                                                  |
+| `prompt`, `setPrompt(text)`, `insertText(text)`     | The prompt. `insertText` replaces the selection or inserts at the cursor.                                                                                                                                                                                                                                 |
+| `attachments`, `addAttachment`, `removeAttachment`  | Items from [your own attachment sources](#add-a-composer-attachment-source). Attachments from other plugins and Paseo's own are not listed.                                                                                                                                                               |
+| `agent.provider`, `model`, `mode`, `thinking`       | What the agent runs with, or what the draft will create.                                                                                                                                                                                                                                                  |
+| `agent.options`                                     | The provider options in effect, defaults included. In a draft: the options the agent will be created with, including your changes.                                                                                                                                                                        |
+| `agent.metadata`                                    | The agent's [metadata](/docs/plugins/hooks#metadata). In New workspace, the first agent's.                                                                                                                                                                                                                |
+| `setProvider`, `setModel`, `setMode`, `setThinking` | Return promises. `setProvider` resets the model like the provider picker. It rejects on `context: "agent"`, which keeps its provider, and for a provider the host does not offer. `setModel` and `setThinking` pass the value on as given; on a running agent the provider's refusal rejects the promise. |
+| `setOptions(patch)`, `setMetadata(patch)`           | Top-level keys replace; `null` removes the key. Metadata set in a draft is sent when the agent is created and cleared once the prompt is sent.                                                                                                                                                            |
+
+The same call does the same thing in every composer; a plugin does not choose a composer's
+implementation. `setMetadata` on a running agent needs a host that supports metadata. On an older
+host the promise rejects with "Update the host to use metadata."
+
+`Toggle` takes `value` and `onValueChange({ value })`. `Select` takes `value`, `options` (`{ value, label,
+description? }`) and `onValueChange({ value })`. `Action` takes `onPress(event)`. All three take `title`,
+`icon` (a [Lucide name, SVG or component](#icons)) and `disabled`. A callback may return a promise:
+the control stays disabled until it settles, and Paseo shows a rejection to the user as an error
+toast, the way it does for its own controls. Paseo owns where each control sits: inline in the
+toolbar when the composer has room, and a row in the composer's overflow sheet when it does not,
+which is always the case on a phone. A `Select` opens its list in place of the sheet row. A
+`Component` that renders something other than these controls draws it where its item is placed; in
+the overflow sheet that is the sheet.
+
+Each command acts on the composer's state when it runs, not on the render that created your
+callback, so `await composer.setProvider("codex")` followed by `await composer.setModel("gpt")`
+changes both. A command's promise resolves once the change has taken effect, and `composer.agent`
+shows it on the next render.
+
+While the New workspace screen creates the workspace and its agent, the composer is locked. Your
+controls render disabled, `setPrompt` and `insertText` throw, and the agent commands reject with
+"The composer is locked while the agent is being created." `composer.agent.options` and
+`composer.agent.metadata` are frozen copies; change them through `setOptions` and `setMetadata`.
+
+A composer item counts toward how much fits before Paseo knows what it renders. An item that
+renders nothing can still leave an empty overflow sheet on a narrow composer, so always render a
+control.
+
+The [composer controls example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/composer-controls)
+registers a `Select`, two `Toggle`s (one writes a provider option) and an `Action`, plus an
+Explorer panel and a Command Center item that reach a composer by reference.
+
+### Reach a composer by reference
+
+A running agent has a composer whether or not its tab is open. `useComposers(selector)` in any plugin
+component, and `composers(selector)` on every command context, return the same `PluginComposer` that
+`useComposer()` gives an item, for an agent you name or for the focused one:
+
+```tsx
+import { useComposers, type PluginClientContext } from "@getpaseo/plugin/client";
+
+function InsertChecklist() {
+  const [focused] = useComposers({ focused: true });
+  return (
+    <Pressable disabled={!focused} onPress={() => focused?.insertText("- [ ] Tests\n")}>
+      <Text>Insert checklist</Text>
+    </Pressable>
+  );
+}
+
+export default function contribute(client: PluginClientContext) {
+  client.addWorkspacePanel({
+    id: "tools",
+    title: "Tools",
+    icon: "ListChecks",
+    locations: ["explorer"],
+    Component: InsertChecklist,
+  });
+  client.addCommandCenterItem({
+    id: "mark-for-review",
+    title: "Mark for review",
+    icon: "Flag",
+    context: "agent",
+    async onSelect({ agent, composers }) {
+      for (const composer of composers({ agentId: agent.id })) {
+        await composer.setMetadata({ "review.needsReview": true });
+      }
+    },
+  });
+  return () => {};
+}
+```
+
+| Selector            | Result                                                                                                                                                                                                                                                                                       |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `{ agentId }`       | The composer of that agent on this host. Empty for an agent that is unknown or archived.                                                                                                                                                                                                     |
+| `{ focused: true }` | The composer of the agent the Command Center hands to agent items: the focused agent tab of the workspace on screen. Empty when the screen is not a workspace, such as a plugin screen or New workspace, or when the focused tab is not an agent. It follows focus as the user changes tabs. |
+
+The result is always an array, empty or with one composer, so the same code reads either selector.
+`useComposers` re-renders when a composer changes. A composer from `composers()` is the state at the
+call; call `composers()` again for the next state.
+
+The commands are those of [`useComposer()`](#composer-items), with these differences for a composer
+you reach from outside:
+
+- `insertText` inserts at the cursor while the agent's composer is on screen. While it is not, for
+  example when the user is in another workspace, it appends to the agent's saved prompt, and the text
+  is in the input when the user returns. `setPrompt` replaces the saved prompt the same way.
+- A running agent's composer is never locked.
+- `setProvider` rejects, as it does inside the agent's own composer.
+- `setModel` and `setThinking` send the value to the provider unchecked. A value the provider refuses
+  rejects with the provider's message. `model` and `thinking` read what the model picker
+  shows at that moment: until the provider's catalog loads that is the id the agent reports or was
+  created with, which may be an alias, and once it loads the catalog's own id.
+- Drafts and the New workspace screen are not addressable by reference. Only an item inside one
+  reaches its composer, through `useComposer()`.
+
+## New workspace items
+
+`client.addNewWorkspaceItem({ id, Component })` puts a field on the New workspace screen, beside
+the project, host and branch pickers. `useNewWorkspace()` reads and changes what the screen will
+create, and `Combobox`, `Select`, `Toggle` and `Action` from `@getpaseo/plugin/client/ui` draw the
+fields. On desktop an item is a badge in the setup row; on a phone it is a full-width field.
+
+```tsx
+import { useNewWorkspace, useRpc, type PluginClientContext } from "@getpaseo/plugin/client";
+import { Combobox } from "@getpaseo/plugin/client/ui";
+import { searchIssuesRpc } from "../shared/issues";
+
+function IssueField() {
+  const newWorkspace = useNewWorkspace();
+  const searchIssues = useRpc(searchIssuesRpc);
+  const issueId = newWorkspace.metadata["issues.id"];
+  return (
+    <Combobox
+      title="Issue"
+      icon="CircleDot"
+      value={typeof issueId === "string" ? { id: issueId, label: issueId } : null}
+      search={async ({ query }) => (await searchIssues({ query })).issues}
+      onSelect={async ({ item }) => {
+        await newWorkspace.setBranch(item.branch);
+        await newWorkspace.setMetadata({ "issues.id": item.id });
+      }}
+    />
+  );
+}
+
+export default function contribute(client: PluginClientContext) {
+  client.addNewWorkspaceItem({ id: "issue", Component: IssueField });
+  return () => {};
+}
+```
+
+`useNewWorkspace()` returns the setup the item sits in:
+
+| Field or command            | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `host`, `project`           | The user's choices, `{ id, label }` and `{ id, name } \| null`. Read-only: an item cannot switch host or project.                                                                                                                                                                                                                                                                                                                                     |
+| `isolation`, `setIsolation` | `"local"` or `"worktree"`. A project that cannot make worktrees reads `"local"`, and `setIsolation("worktree")` rejects.                                                                                                                                                                                                                                                                                                                              |
+| `baseRef`, `setBaseRef`     | What a new worktree starts from: `{ type: "branch", name }`, `{ type: "change-request", number }`, or `null` until the default is known. A branch's `name` is the exact ref creation uses, such as `refs/remotes/origin/main`, so `setBaseRef(newWorkspace.baseRef)` changes nothing. `setBaseRef` takes any ref the Base picker offers, or a bare branch name, which Paseo resolves as it does anywhere else. It rejects while no project is chosen. |
+| `branch`, `setBranch`       | The name of the branch a new worktree is created on. `null` lets Paseo pick one. It is kept while isolation is local or the base is a change request, and it names the new branch of any worktree that cuts one, from the default base or a chosen branch. It does not apply to a worktree that checks out an existing branch or change request.                                                                                                      |
+| `metadata`, `setMetadata`   | The created workspace's [metadata](/docs/plugins/hooks#metadata), not the first agent's. Top-level keys replace; `null` removes a key. Rejects on a host that does not support metadata with "Update the host to use metadata."                                                                                                                                                                                                                       |
+
+Commands follow the [composer item](#composer-items) rules: each one acts on the screen's state
+when it runs, so `await newWorkspace.setBranch(name)` followed by `newWorkspace.setMetadata(patch)`
+changes both, and its promise resolves once the change has taken effect. A command works from your component's first effect, including a mount effect. Payloads are JSON values.
+Your items are mounted for one project on one host. When the user changes either, Paseo remounts them and clears `branch` and `metadata`, so state and `Combobox` results for the previous project do not carry over; an item that sets up in a mount effect sets up again for the new project. A command called after its project or host has been left, such as the end of a lookup the user abandoned by switching, rejects with "The New workspace screen moved to another project or host; this item belongs to the previous one." and changes nothing; the items mounted for the new project are not affected.
+`host`, `project`, `baseRef` and `metadata` are frozen. While the screen creates the workspace it is locked: your fields render
+disabled and every command rejects with "The New workspace screen is locked while the workspace is
+being created." A callback that returns a promise keeps the control disabled until it settles, and a
+rejection reaches the user as an error toast.
+
+`Combobox` is a field with a searchable list whose results come from your code:
+
+| Prop       | Meaning                                                                                                                                                                               |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`    | `{ id, label, description? } \| null`, what the field shows. It need not be among the search results, so it can show a choice made earlier.                                           |
+| `search`   | `({ query }) => Promise<Item[]>`. Called with `""` when the list opens and again, debounced, as the user types. Each `Item` is `{ id, label, description? }` plus any fields you add. |
+| `onSelect` | `({ item }) => void \| Promise<void>`. `item` is the object `search` returned.                                                                                                        |
+
+Paseo shows "Searching…" while a search runs, "Search failed" with the error message when it
+rejects, and an empty state for no results. It keeps the previous results while a newer search runs
+and ignores a search that a newer one replaced, so `search` needs no cancellation of its own.
+`Combobox` takes the same `title`, `icon` and `disabled` as the other controls, and draws as a row
+with a list in the composer's overflow sheet too.
+
+The [New workspace issues example](https://github.com/getpaseo/paseo/tree/main/plugin-examples/new-workspace-issues)
+searches a fixed issue list from a daemon handler and sets the branch and metadata from the choice.
+
 ## Composer pills

 `client.addComposerPill({ id, workspaceId, agentId, button })` uses the same [button descriptor](#button-descriptor)
@@ -353,13 +353,13 @@ Paseo 为服务端代码提供 `@getpaseo/plugin`、`@getpaseo/plugin/server`、

 ### Provider {#providers}

-直接实现和 ACP 实现、会话生命周期、Composer 设置、时间线渲染器、测试和分发，见[构建 Provider 插件](/docs/plugins/providers)。
+直接实现和 ACP 实现、会话生命周期、选项控件、时间线渲染器、测试和分发，见[构建 Provider 插件](/docs/plugins/providers)。

 使用来自 `@getpaseo/plugin/server/provider` 的 `ProviderRegistration` 调用 `server.registerProvider()`。它的连接通过 `send()` 接收输入，并通过 `onEvent()` 发出完整的状态快照。`send()` 只报告是否接受；提示词的处理结果、轮次、配置、持久化、权限和失败都是事件。

 消息、结构化命令、引导和命令副作用都使用同一个 `session.prompt` 输入。在实时的用户时间线条目上重复 `clientMessageId`，并恰好发布一个与之匹配的 `session.prompt_result`。把 Provider 创建的子会话发布为带有 `parentSessionId` 的会话。

-Provider 设置是 Paseo 在 Composer 中渲染的开关/选择描述符。把 Provider 私有的选项保留在 `session.open` 的 `ProviderSessionConfig.providerOptions` 中。这个记录包含配置的默认值和针对单个 Agent 的覆盖值；请在你的 Provider 中校验并应用它。配置和合并语义见 [Provider 选项](/docs/sdk/provider-options)。宿主工具以 MCP 服务器的形式出现在完整的会话配置中。
+Provider 选项是一个记录，即 `session.open` 中的 `ProviderSessionConfig.providerOptions`。它包含配置的默认值和针对单个 Agent 的覆盖值；请在你的 Provider 中校验并应用它。在 `session.config` 中为需要在 Composer 里显示开关或选择器的顶层键报告 `controls`，并在 `providerOptions` 下报告会话正在使用的值。运行中会话的修改会以 `session.configure` 的形式到达，内容在 `changes.providerOptions` 中。配置和合并语义见 [Provider 选项](/docs/sdk/provider-options)。宿主工具以 MCP 服务器的形式出现在完整的会话配置中。

 Paseo 刷新 Agent 的方式是关闭它当前的 Provider 会话，再用当前的配置和持久化值打开它。Provider 在 `session.open` 期间重新读取外部状态。

@@ -1604,6 +1604,182 @@ review.remove();
 贡献移入一个共享的溢出菜单。在手机和较窄的窗口中，标题栏没有空间放置插件按钮，因此每个按钮都会成为工作区
 菜单（`···`）中的一行，显示它的图标和标题；它的菜单和弹出框以该底部面板中的页面打开。位置和溢出由宿主决定。

+## Composer 项 {#composer-items}
+
+`client.addComposerItem({ id, Component })` 把一个组件放进 composer：Agent composer、为新 Agent 准备的草稿 composer，以及新建工作区界面上的 composer。`useComposer()` 读取并修改 composer 所配置的内容，`@getpaseo/plugin/client/ui` 中的 `Toggle`、`Select` 和 `Action` 负责绘制控件。
+
+```tsx
+import { useComposer, type PluginClientContext } from "@getpaseo/plugin/client";
+import { Action, Select, Toggle } from "@getpaseo/plugin/client/ui";
+
+function ReviewFlag() {
+  const composer = useComposer();
+  return (
+    <Toggle
+      title="Needs review"
+      icon="Flag"
+      value={composer.agent.metadata["review.needsReview"] === true}
+      onValueChange={({ value }) =>
+        composer.setMetadata({ "review.needsReview": value ? true : null })
+      }
+    />
+  );
+}
+
+function Checklist() {
+  const composer = useComposer();
+  return (
+    <Action
+      title="Insert checklist"
+      icon="ListChecks"
+      onPress={() => composer.insertText("- [ ] Tests\n- [ ] Docs\n")}
+    />
+  );
+}
+
+export default function contribute(client: PluginClientContext) {
+  client.addComposerItem({ id: "review-flag", Component: ReviewFlag });
+  client.addComposerItem({ id: "checklist", Component: Checklist });
+  return () => {};
+}
+```
+
+`useComposer()` 返回该项所在的 composer：
+
+| 字段或命令                                          | 含义                                                                                                                                                                                                                                                         |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `context`                                           | `"agent"` 表示运行中的 Agent，`"draft"` 表示工作区中的新 Agent，`"new-workspace"` 表示新建工作区界面。                                                                                                                                                       |
+| `prompt`、`setPrompt(text)`、`insertText(text)`     | 提示词。`insertText` 会替换选区，或在光标处插入。                                                                                                                                                                                                            |
+| `attachments`、`addAttachment`、`removeAttachment`  | 来自[你自己的附件来源](#add-a-composer-attachment-source)的项目。其他插件和 Paseo 自身的附件不会列出。                                                                                                                                                       |
+| `agent.provider`、`model`、`mode`、`thinking`       | Agent 当前使用的配置，或草稿将要创建的配置。                                                                                                                                                                                                                 |
+| `agent.options`                                     | 当前生效的 Provider 选项，包含默认值。在草稿中：创建 Agent 时将使用的选项，包含你所做的修改。                                                                                                                                                                |
+| `agent.metadata`                                    | Agent 的[元数据](/docs/plugins/hooks#metadata)。在新建工作区中是第一个 Agent 的元数据。                                                                                                                                                                      |
+| `setProvider`、`setModel`、`setMode`、`setThinking` | 返回 Promise。`setProvider` 会像 Provider 选择器一样重置模型。在 `context: "agent"` 下（运行中的 Agent 保持其 Provider）以及主机不提供该 Provider 时会被拒绝。`setModel` 和 `setThinking` 原样传递该值；对运行中的 Agent，Provider 拒绝时 Promise 会被拒绝。 |
+| `setOptions(patch)`、`setMetadata(patch)`           | 顶层键替换，`null` 删除该键。草稿中设置的元数据在创建 Agent 时发送，发送提示词后清空。                                                                                                                                                                       |
+
+同一个调用在每个 composer 中行为一致，插件不需要选择 composer 的实现。在运行中的 Agent 上调用 `setMetadata` 需要支持元数据的主机；主机过旧时，Promise 会以 “Update the host to use metadata.” 拒绝。
+
+`Toggle` 接收 `value` 和 `onValueChange({ value })`。`Select` 接收 `value`、`options`（`{ value, label, description? }`）和 `onValueChange({ value })`。`Action` 接收 `onPress(event)`。三者都接收 `title`、`icon`（[Lucide 名称、SVG 或组件](#icons)）和 `disabled`。回调可以返回 Promise：在它完成之前控件保持禁用，被拒绝时 Paseo 会像对待自身控件一样，以错误提示向用户显示。控件的位置由 Paseo 决定：composer 空间足够时显示在工具栏中，不够时（手机上始终如此）成为 composer 溢出面板中的一行。`Select` 会就地打开列表，而不是替换面板中的行。`Component` 如果渲染这些控件以外的内容，会在其所在位置绘制；在溢出面板中，该位置就是面板。
+
+每个命令都按运行时 composer 的当前状态执行，而不是按创建回调的那次渲染，所以 `await composer.setProvider("codex")` 之后再 `await composer.setModel("gpt")` 会同时生效。命令的 Promise 在更改生效后完成，`composer.agent` 在下一次渲染时反映它。
+
+新建工作区界面在创建工作区及其 Agent 期间会锁定 composer。你的控件显示为禁用，`setPrompt` 和 `insertText` 会抛出错误，Agent 命令会以 "The composer is locked while the agent is being created." 拒绝。`composer.agent.options` 和 `composer.agent.metadata` 是冻结的副本；请通过 `setOptions` 和 `setMetadata` 修改它们。
+
+在 Paseo 知道渲染结果之前，composer 项就已计入可容纳的数量。不渲染任何内容的项仍可能在窄 composer 上留下空的溢出面板，所以请始终渲染一个控件。
+
+[Composer 控件示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/composer-controls)注册了一个 `Select`、两个 `Toggle`（其中一个写入 Provider 选项）和一个 `Action`，还有一个资源管理器面板和一个 Command Center 条目，它们按引用访问 composer。
+
+### 按引用访问 composer {#reach-a-composer-by-reference}
+
+运行中的 Agent 无论标签页是否打开，都有自己的 composer。任意插件组件中的 `useComposers(selector)`，以及每个命令上下文中的 `composers(selector)`，都会返回与 `useComposer()` 给 composer 项的相同的 `PluginComposer`，对象可以是你指定的 Agent，也可以是当前聚焦的 Agent：
+
+```tsx
+import { useComposers, type PluginClientContext } from "@getpaseo/plugin/client";
+
+function InsertChecklist() {
+  const [focused] = useComposers({ focused: true });
+  return (
+    <Pressable disabled={!focused} onPress={() => focused?.insertText("- [ ] Tests\n")}>
+      <Text>Insert checklist</Text>
+    </Pressable>
+  );
+}
+
+export default function contribute(client: PluginClientContext) {
+  client.addWorkspacePanel({
+    id: "tools",
+    title: "Tools",
+    icon: "ListChecks",
+    locations: ["explorer"],
+    Component: InsertChecklist,
+  });
+  client.addCommandCenterItem({
+    id: "mark-for-review",
+    title: "Mark for review",
+    icon: "Flag",
+    context: "agent",
+    async onSelect({ agent, composers }) {
+      for (const composer of composers({ agentId: agent.id })) {
+        await composer.setMetadata({ "review.needsReview": true });
+      }
+    },
+  });
+  return () => {};
+}
+```
+
+| 选择器              | 结果                                                                                                                                                                                                 |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `{ agentId }`       | 此主机上该 Agent 的 composer。Agent 未知或已归档时为空。                                                                                                                                             |
+| `{ focused: true }` | Command Center 交给 Agent 项的那个 Agent 的 composer：屏幕上工作区中聚焦的 Agent 标签页。当前界面不是工作区（例如插件界面或新建工作区），或聚焦的标签页不是 Agent 时为空，并随用户切换标签页而变化。 |
+
+结果始终是数组，为空或只含一个 composer，所以同一段代码可以读取任一选择器。composer 变化时 `useComposers` 会重新渲染。`composers()` 返回的 composer 是调用时的状态，要获取下一个状态请再次调用 `composers()`。
+
+命令与 [`useComposer()`](#composer-items) 相同，从外部访问时有以下差异：
+
+- Agent 的 composer 在屏幕上时，`insertText` 在光标处插入。不在屏幕上时（例如用户在另一个工作区），它会追加到该 Agent 已保存的提示词，用户回来时文本就在输入框里。`setPrompt` 以同样的方式替换已保存的提示词。
+- 运行中 Agent 的 composer 从不锁定。
+- `setProvider` 会被拒绝，与在 Agent 自己的 composer 内一样。
+- `setModel` 和 `setThinking` 不加检查地把值发给 Provider。Provider 拒绝的值会以 Provider 的消息拒绝。`model` 和 `thinking` 读取的是模型选择器此刻显示的值：在 Provider 的模型目录加载完成之前，是 Agent 上报或创建时使用的 id（可能是别名），加载完成后是目录中的 id。
+- 草稿和新建工作区界面不能按引用访问，只有其中的项能通过 `useComposer()` 访问其 composer。
+
+## 新建工作区项 {#new-workspace-items}
+
+`client.addNewWorkspaceItem({ id, Component })` 在新建工作区界面上放置一个字段，位于项目、主机和分支选择器旁边。`useNewWorkspace()` 读取并修改界面将要创建的内容，`@getpaseo/plugin/client/ui` 中的 `Combobox`、`Select`、`Toggle` 和 `Action` 负责绘制字段。桌面端的项是设置行中的徽章；手机上是整行宽度的字段。
+
+```tsx
+import { useNewWorkspace, useRpc, type PluginClientContext } from "@getpaseo/plugin/client";
+import { Combobox } from "@getpaseo/plugin/client/ui";
+import { searchIssuesRpc } from "../shared/issues";
+
+function IssueField() {
+  const newWorkspace = useNewWorkspace();
+  const searchIssues = useRpc(searchIssuesRpc);
+  const issueId = newWorkspace.metadata["issues.id"];
+  return (
+    <Combobox
+      title="Issue"
+      icon="CircleDot"
+      value={typeof issueId === "string" ? { id: issueId, label: issueId } : null}
+      search={async ({ query }) => (await searchIssues({ query })).issues}
+      onSelect={async ({ item }) => {
+        await newWorkspace.setBranch(item.branch);
+        await newWorkspace.setMetadata({ "issues.id": item.id });
+      }}
+    />
+  );
+}
+
+export default function contribute(client: PluginClientContext) {
+  client.addNewWorkspaceItem({ id: "issue", Component: IssueField });
+  return () => {};
+}
+```
+
+`useNewWorkspace()` 返回该项所在的设置：
+
+| 字段或命令                  | 含义                                                                                                                                                                                                                                                                                                                                                                    |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `host`、`project`           | 用户的选择，分别是 `{ id, label }` 和 `{ id, name } \| null`。只读：项不能切换主机或项目。                                                                                                                                                                                                                                                                              |
+| `isolation`、`setIsolation` | `"local"` 或 `"worktree"`。无法创建 worktree 的项目读取为 `"local"`，此时 `setIsolation("worktree")` 会被拒绝。                                                                                                                                                                                                                                                         |
+| `baseRef`、`setBaseRef`     | 新 worktree 的起点：`{ type: "branch", name }`、`{ type: "change-request", number }`，默认值未知时为 `null`。分支的 `name` 是创建时实际使用的完整 ref，例如 `refs/remotes/origin/main`，所以 `setBaseRef(newWorkspace.baseRef)` 不会改变任何内容。`setBaseRef` 接受 Base 选择器提供的任何 ref，或一个裸分支名，Paseo 会按其他地方一贯的方式解析。未选择项目时会被拒绝。 |
+| `branch`、`setBranch`       | 新 worktree 所创建的分支名称。`null` 表示由 Paseo 选择名称。隔离为本地或起点为变更请求时会保留该值，它为任何新建分支的 worktree 命名，起点可以是默认基线或所选分支；检出已有分支或变更请求的 worktree 不适用。                                                                                                                                                          |
+| `metadata`、`setMetadata`   | 所创建工作区的[元数据](/docs/plugins/hooks#metadata)，而不是第一个 Agent 的元数据。顶层键替换，`null` 删除该键。主机不支持元数据时以 “Update the host to use metadata.” 拒绝。                                                                                                                                                                                          |
+
+命令遵循 [Composer 项](#composer-items)的规则：每个命令都按界面运行时的状态执行，所以 `await newWorkspace.setBranch(name)` 之后再调用 `newWorkspace.setMetadata(patch)` 会同时生效，命令的 Promise 在更改生效后完成。命令从组件的第一个 effect 起即可使用，包括挂载时的 effect。载荷是 JSON 值。你的项针对某一台主机上的某一个项目挂载。用户更改其中任何一个时，Paseo 会重新挂载你的项并清除 `branch` 和 `metadata`，因此上一个项目的状态和 `Combobox` 结果不会保留；在挂载 effect 中做初始化的项会针对新项目再次初始化。在其项目或主机已被离开之后才调用的命令（例如用户切换项目时被放弃的查询最终返回）会以 "The New workspace screen moved to another project or host; this item belongs to the previous one." 拒绝，并且不做任何更改；为新项目挂载的项不受影响。`host`、`project`、`baseRef` 和 `metadata` 是冻结的。界面创建工作区期间会被锁定：你的字段显示为禁用，所有命令都会以 "The New workspace screen is locked while the workspace is being created." 拒绝。返回 Promise 的回调在完成之前会让控件保持禁用，被拒绝时会以错误提示向用户显示。
+
+`Combobox` 是带可搜索列表的字段，结果由你的代码提供：
+
+| 属性       | 含义                                                                                                                                              |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`    | `{ id, label, description? } \| null`，字段显示的内容。它不必出现在搜索结果中，因此可以显示之前所做的选择。                                       |
+| `search`   | `({ query }) => Promise<Item[]>`。列表打开时以 `""` 调用，之后随用户输入防抖调用。每个 `Item` 是 `{ id, label, description? }` 加上你添加的字段。 |
+| `onSelect` | `({ item }) => void \| Promise<void>`。`item` 就是 `search` 返回的对象。                                                                          |
+
+搜索进行时 Paseo 显示 “Searching…”，搜索被拒绝时显示 “Search failed” 和错误信息，没有结果时显示空状态。新搜索进行期间会保留之前的结果，并忽略已被更新搜索取代的结果，所以 `search` 不需要自己处理取消。`Combobox` 接收与其他控件相同的 `title`、`icon` 和 `disabled`。
+
+[新建工作区 Issue 示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/new-workspace-issues)通过守护进程处理器搜索一个固定的 Issue 列表，并根据所选项设置分支和元数据。
+
 ## Composer 胶囊 {#composer-pills}

 `client.addComposerPill({ id, workspaceId, agentId, button })` 使用同样的[按钮描述符](#button-descriptor)，