kward 0.84.0 → 0.85.0

data/doc/rpc.md

@@ -15,7 +15,7 @@ A typical client launches the server, sends `initialize`, creates or resumes a s
 | Connect and negotiate capabilities | [Launch](#Launch), [Framing](#Framing), and [Initialization](#Initialization) |
 | Open, resume, branch, or export a conversation | [Session methods](#Session_methods) |
 | Send input and render a response | [Turn methods](#Turn_methods) and [Turn notifications](#Turn_notifications) |
-| Handle tool approval or structured questions | [Tool approval bridge](#Tool_approval_bridge) and [UI question bridge](#UI_question_bridge) |
+| Handle tool approval or structured plugin UI | [Tool approval bridge](#Tool_approval_bridge) and [Structured UI bridge](#Structured_UI_bridge) |
 | Show model, runtime, auth, or configuration controls | [Runtime methods](#Runtime_methods), [Model methods](#Model_methods), and [Config and auth methods](#Config_and_auth_methods) |
 | Discover tools, MCP servers, prompts, skills, or plugins | [Tool and prompt methods](#Tool_and_prompt_methods) |
 
@@ -65,8 +65,10 @@ Read `capabilities` at runtime instead of assuming every feature is available. I
 - `transcript`: Kward transcript format support, including normalized messages, image/tool support, compaction summaries, and restored assistant reasoning as Pi-compatible `thinking` content blocks.
 - `sessions`: explicit RPC session mode, JSONL persistence, and methods for listing, auto-resume, live-session discovery, linear forking, compaction, and labeled tree navigation with branch summaries. Import is unsupported. Live session updates are also unsupported but reserve the `session/updated` notification name. Git worktree bindings are reported as interactive-TUI-only.
 - `turns`: asynchronous turns, per-session concurrency, active and recent turn lists, busy-input steering when the provider supports it, queued follow-ups, best-effort cancellation, and recent in-memory event replay. Per-turn options cover model, reasoning, tool scope, and tool approval, with structured client context for editor integrations.
-- `pluginChats`: optional plugin-owned chats. The capability lists opted-in chat types and methods. Clients must explicitly subscribe before receiving `pluginChat/event` notifications; plugin chats are independent from workspace sessions. A type may also report `transport: true` when a trusted external transport is allowed to target it; RPC opt-in and external transport opt-in remain separate.
-- `events`: the `turn/event` contract, assistant and reasoning events, normalized tool metadata, tool updates and results, diff support, workspace guardrail status, focused-context and context-budget statistics tools, and explicitly unsupported shell changed-file and session-update flags.
+- `plugins`: the supported plugin API version and public `id`, `version`, and `apiVersion` metadata for identified plugins. Private plugin configuration is never included.
+- `pluginTools`: model-callable tools registered by trusted local plugins, including the registered count, `tools/list` discovery, execution-profile filtering, and permission-policy enforcement.
+- `pluginChats`: optional plugin-owned chats. The capability lists opted-in chat types and methods. Versioned types report declared attachment, steering, and transcript-paging capabilities. Clients must explicitly subscribe before receiving `pluginChat/event` notifications; plugin chats are independent from workspace sessions. A type may also report `transport: true` when a trusted external transport is allowed to target it; RPC opt-in and external transport opt-in remain separate.
+- `events`: the `turn/event` contract, assistant and reasoning events, typed plugin-command results, normalized tool metadata, tool updates and results, diff support, workspace guardrail status, focused-context and context-budget statistics tools, and explicitly unsupported shell changed-file and session-update flags.
 - `attachments`: supported input attachment contract for `turns/start`, with accepted base64 image MIME types and a stable max byte value.
 - `models`: model listing, refresh, selection, and exposed metadata across providers. Scoped model selection is not supported.
 - `runtime`: runtime state, message-count statistics, and OpenAI/Codex context usage. Kward does not yet compute cumulative token or cost statistics.
@@ -74,12 +76,13 @@ Read `capabilities` at runtime instead of assuming every feature is available. I
 - `runtimeSettings`: live `runtime/updateSetting` support for `defaultModel` and `defaultThinkingLevel`, plus `runtime/reload`.
 - `auth`: available providers and authentication methods, private API-key storage, sanitized status, and logout. OpenAI and Anthropic OAuth are supported; Copilot OAuth is CLI-only, OpenRouter PKCE is not implemented, and xAI has no supported stable third-party flow.
 - `memory`: opt-in structured memory support, interactive prompt injection only, JSON/JSONL local storage, and dedicated `memory/*` methods.
-- `commands`: supported `commands/list` capability for prompt, skill, and plugin command sources, plus plugin execution through `commands/run` or plugin slash turns.
+- `commands`: supported `commands/list` capability for prompt, skill, and plugin command sources, plus plugin execution through `commands/run` or plugin slash turns. Plugin commands may advertise validated JSON Schema arguments, shell-style text parsing, and structured results while legacy raw-string commands remain supported.
+- `pluginActions`: namespaced typed actions discovered through `pluginActions/list` and synchronously invoked through `pluginActions/run`. They use object arguments and structured results, are not local TUI commands, and cannot make blocking UI requests.
 - `skillCapture`: capture a reviewed personal `SKILL.md` from any saved session’s active branch through `skills/captureSessions`, `skills/captureDraft`, and `skills/saveCapturedDraft`.
 - `projectSkillTrust`: explicitly unsupported over RPC. RPC clients cannot answer the interactive Allow/Deny/Review decision, so project skills remain skipped unless the global `skills.trust_project` override is enabled.
 - `mcp`: local stdio MCP server support through the shared `mcpServers` config. RPC exposes MCP tools to turns and advertises discovery with `methods: ["tools/list", "mcp/status"]`, `toolMetadata: true`, and `serverStatus: true`. It does not support MCP resources, prompts, sampling, or Streamable HTTP.
 - `startupResources`: supported startup resource listing for context, skills, prompts, and plugins.
-- `extensionUi`: question bridge support via `ui/question` and `ui/answerQuestion`, plus plugin footer updates via `ui/footer`; other UI primitives are explicitly unsupported.
+- `extensionUi`: structured question support plus plugin `select`, `confirm`, `input`, `progress`, and `notify` UI through `ui/request`, `ui/answerRequest`, `ui/progress`, and `ui/notification`; plugin footer updates use `ui/footer`. Editor, widget, custom-canvas, and raw terminal-input primitives remain explicitly unsupported.
 - `composer`: composer-only UI features. Interactive session diff totals are explicitly unsupported over RPC (`composer.sessionDiff.supported: false`) because RPC clients already receive per-tool diff results and no live composer status payload is exposed. Clipboard copy is also unsupported over RPC (`composer.copy.supported: false`) because UI clients own clipboard access. Vibe editor prompts are unsupported over RPC (`composer.editorPrompt.supported: false`) because RPC has no live integrated editor buffer.
 - `security`: trusted-local behavior and optional per-turn tool approval. By default, RPC turns have no workspace mutation guard or tool approval, so shell commands and file changes can run. Clients can inspect file-tool guardrails through `capabilities.events.tools.workspaceGuardrails` and `runtime/state.workspaceGuardrailsEnabled`. `security.sandbox` reports the command sandbox mode, enforcement backend, and filesystem and network capabilities; session pinning and one-time elevation are unsupported. See [Command sandboxing](sandboxing.md) for the boundary and its limits.
 - `export`: supported transcript export formats. Currently `markdown` and `html`; default is `markdown`.
@@ -294,7 +297,11 @@ Returns `{ "session": {}, "editorText": "...", "cancelled": false, "aborted": fa
 
 ## Plugin chat methods
 
-Plugin chats are optional trusted-plugin capabilities, not Kward workspace sessions. When `initialize.capabilities.pluginChats.supported` is true, use `pluginChats/list` to discover available types.
+Plugin chats are optional trusted-plugin capabilities, not Kward workspace
+sessions. When `initialize.capabilities.pluginChats.supported` is true, use
+`pluginChats/list` to discover available types. Types using the versioned chat
+contract also report `apiVersion` and `capabilities` with `attachments`,
+`steering`, and `transcriptPaging`; legacy types omit those fields.
 
 ### `pluginChats/open`
 
@@ -330,7 +337,10 @@ Params:
 - `input`;
 - `attachments`: optional base64 image attachments using the same MIME and size limits as `turns/start`.
 
-Queues a plugin-chat turn and returns `{ id, chatId, status, ... }`. Plugin chat turns are serialized per chat and do not use workspace sessions, agents, or model overrides.
+Queues a plugin-chat turn and returns `{ id, chatId, status, ... }`. Plugin chat
+turns are serialized per chat and do not use workspace sessions, agents, or
+model overrides. A versioned chat whose declared `attachments` capability omits
+`image` rejects image attachments before invoking its driver.
 
 ### `pluginChats/turns/cancel`, `pluginChats/turns/status`, `pluginChats/turns/events`, `pluginChats/turns/list`, `pluginChats/turns/listActive`
 
@@ -439,6 +449,7 @@ Known event types:
 - `toolCall`
 - `toolUpdate`
 - `toolResult`
+- `pluginCommandResult`
 - `answer`
 - `turnCancelRequested`
 - `error`
@@ -462,6 +473,10 @@ Lifecycle payloads include `status` for `turnQueued`, `turnStarted`, and `turnFi
 
 `toolResult` additionally includes `result` with `content`, `isError`, optional unified `diff`, optional `changedFiles`, and `images`. Failed or declined tools set `isError: true`.
 
+A typed plugin slash command emits `pluginCommandResult` with `command` and a
+structured `result` containing optional `message` and `data` fields. It then
+emits the usual text events when the command produced user-facing output.
+
 Examples:
 
 - `edit_file`: `toolName: "edit"`, `args: { "path": "...", "edits": [{ "oldText": "...", "newText": "..." }] }`.
@@ -490,11 +505,11 @@ Params:
 
 Denied tools are returned to the model as error-like tool results instead of executing the local operation.
 
-## UI question bridge
+## Structured UI bridge
 
-Kward supports the structured question bridge and plugin footer updates over RPC. The `extensionUi` capability reports `question.supported: true` with `notification: "ui/question"`, `method: "ui/answerQuestion"`, `maxQuestions: 4`, `multiSelect: false`, and `preview: false`. It also reports `footer.supported: true` with `notification: "ui/footer"`. Other Pi-style extension UI primitives (`select`, `confirm`, `input`, `editor`, `widgets`, `custom`, and `terminalInput`) are explicitly reported as unsupported until Kward has a real plugin/extension consumer for them.
+Kward supports model questions and frontend-neutral plugin UI over RPC. The `extensionUi` capability reports the notification and answer method for each operation. `question` continues to use `ui/question` and `ui/answerQuestion`; plugin `select`, `confirm`, and `input` requests use `ui/request` and `ui/answerRequest`. Non-blocking plugin updates use `ui/progress` and `ui/notification`, while plugin footers use `ui/footer`. Editor, widget, custom-canvas, and raw terminal-input primitives remain explicitly unsupported.
 
-Question requests are validated before notification. Kward accepts 1-4 questions, each with 2-4 options, and rejects unsupported `multiSelect` or option `preview` requests.
+Question requests are validated before notification. Kward accepts 1-4 questions, each with 2-4 options, and rejects unsupported `multiSelect` or option `preview` requests. Plugin selections accept at most 100 options, and plugin text input is bounded to 16,384 bytes.
 
 When the model calls `ask_user_question`, RPC emits a `ui/question` notification:
 
@@ -506,16 +521,37 @@ When the model calls `ask_user_question`, RPC emits a `ui/question` notification
 }
 ```
 
-When a loaded Kward plugin registers a footer, RPC emits `ui/footer` after session creation/resume/clone and after each completed turn:
+When loaded Kward plugins contribute footer status, RPC emits `ui/footer` after
+session creation/resume/clone, after each completed turn, and when the status
+changes during its periodic refresh:
 
 ```json
 {
   "sessionId": "...",
-  "text": "custom footer text"
+  "text": "Bridge · 2 messages",
+  "segments": [
+    {
+      "id": "com.example.session/session",
+      "text": "Bridge",
+      "tooltip": "Current Kward session",
+      "priority": "high",
+      "order": 10
+    },
+    {
+      "id": "com.example.session/messages",
+      "text": "2 messages",
+      "priority": "low",
+      "order": 20
+    }
+  ]
 }
 ```
 
-An empty `text` value clears the client footer.
+`text` is the combined fallback for clients that do not render segments.
+`segments` remains display-ordered and lets richer clients show tooltips or
+apply their own width policy. An empty `text` with an empty `segments` array
+clears the client footer. The `extensionUi.footer` capability advertises
+segment, tooltip, and priority support.
 
 The UI must respond with `ui/answerQuestion`:
 
@@ -525,6 +561,40 @@ Params:
 - `questionRequestId`
 - `answers`: answer array returned to the tool.
 
+When a plugin calls `ctx.ui.select`, `ctx.ui.confirm`, or `ctx.ui.input` during an asynchronous plugin-command turn or plugin tool call, RPC emits:
+
+```json
+{
+  "method": "ui/request",
+  "params": {
+    "sessionId": "...",
+    "requestId": "...",
+    "kind": "select",
+    "payload": {
+      "title": "Environment",
+      "message": "Choose a target",
+      "options": [
+        { "label": "Staging", "value": "staging", "description": "Deploy for testing." }
+      ]
+    }
+  }
+}
+```
+
+Answer it with `ui/answerRequest`:
+
+```json
+{
+  "sessionId": "...",
+  "requestId": "...",
+  "value": "staging"
+}
+```
+
+For `confirm`, `value` must be a boolean. For `input`, it is a string or `null` when cancelled. For `select`, it is one of the advertised option values or `null`. Submit interactive plugin commands through `turns/start`; synchronous `commands/run` deliberately reports blocking plugin UI as unavailable so the RPC reader never waits for an answer it cannot read.
+
+`ctx.ui.progress` emits `ui/progress` with `sessionId`, stable `id`, `message`, optional `percent`, and `done`. `ctx.ui.notify` emits `ui/notification` with `sessionId`, `message`, and `level` (`info`, `success`, `warning`, or `error`). These notifications do not require answers.
+
 ## Runtime methods
 
 ### `runtime/state`
@@ -737,11 +807,11 @@ Params:
 
 Returns current tool schemas. The existing model-facing schema shape is preserved: each entry still has `type: "function"` and `function` with `name`, `description`, and `parameters`. Entries also include additive metadata for UI discovery:
 
-- `metadata.source`: one of practical source labels such as `builtin`, `mcp`, `web`, `skill`, `ui`, or `unknown`.
+- `metadata.source`: one of practical source labels such as `builtin`, `plugin`, `mcp`, `web`, `skill`, `ui`, or `unknown`.
 - `metadata.displayName`: human-readable tool label.
 - MCP tools also include `metadata.serverName` and `metadata.remoteName`. The callable name remains sanitized with a double underscore, for example `github__search_issues`, while `displayName` is `github.search_issues`.
 
-Clients that only read `tools[].function` remain compatible.
+Clients that only read `tools[].function` remain compatible. Model-callable tools registered by trusted local plugins appear here with `metadata.source: "plugin"` and follow the same per-session execution-profile filtering as built-in tools.
 
 ### `mcp/status`
 
@@ -766,7 +836,74 @@ Params:
 
 - `sessionId`: active RPC session ID.
 
-Returns frontend-neutral slash command metadata for configured prompt templates, skills, and plugins. Prompt command names omit the leading slash. Skill command names use `skill:<name>`. Plugin command names omit the leading slash and include `executable: true`. Builtin terminal-only commands are omitted. Prompt commands can be submitted directly to `turns/start` as slash commands or expanded first with `prompts/expand`; plugin commands can be submitted to `turns/start` or run explicitly with `commands/run`.
+Returns frontend-neutral slash command metadata for configured prompt templates, skills, and plugins. Prompt command names omit the leading slash. Skill command names use `skill:<name>`. Plugin command names omit the leading slash and include `executable: true`. Typed plugin entries additionally include `typed: true`, their strict object `schema`, declared `positionals`, and `pluginId` when the plugin has stable identity. Builtin terminal-only commands are omitted. Prompt commands can be submitted directly to `turns/start` as slash commands or expanded first with `prompts/expand`; plugin commands can be submitted to `turns/start` or run explicitly with `commands/run`.
+
+### `commands/run`
+
+Params:
+
+- `sessionId`: active RPC session ID.
+- `name`: plugin command name, with or without the leading slash.
+- `arguments`: shell-style text or, for typed commands, an object matching the advertised schema.
+
+Legacy plugin commands return their existing string-or-null `result`. Typed
+commands return `result` as an object containing optional user-facing `message`
+and JSON-compatible `data`; text emitted through `ctx.say` remains in `output`.
+Blocking structured UI requests are unavailable on this synchronous path. Use a
+slash-command `turns/start` call when the command needs interactive UI.
+
+Plugin commands can also stage a model response with `ctx.request_turn(system: text)`.
+Submit these through `turns/start`, for example:
+
+```json
+{"sessionId":"session-id","input":"/iddqd Answer in French and explain the current design."}
+```
+
+The same turn emits the normal model, tool, answer, error, and completion events.
+The host retains cancellation, execution-profile restrictions, and tool approvals.
+The instructions supplement the system prompt for this turn only; they are not
+submitted as user text and are not reactivated by restoring the session.
+`commands/run` and `pluginActions/run` reject model-turn requests. Discover this
+contract under `initialize.capabilities.commands.modelTurns`, including the
+65,536-byte limit, `scope: "turn"`, and `synchronous: false`.
+`inputRole: "system"` describes Kward's internal instruction role;
+`codexInputRole: "developer"` reports the Codex subscription backend's supported
+wire role. Codex receives the command as a new ordered developer message, while
+direct OpenAI Responses receives an ordered system message. Base instructions
+stay separate from these turn-scoped input messages.
+
+The invocation is saved as a user-visible history entry with `display_content`
+and `plugin_system_turn` metadata (command, plugin ID, instruction text, request ID,
+and scope). Later model requests omit these history entries; compaction uses an
+informational placeholder, not the expired instructions. Anthropic and Gemini
+use separate system fields rather than ordered system messages and require
+existing dialogue; a system-only request in an empty session fails explicitly
+rather than inserting a synthetic user prompt.
+
+### `pluginActions/list`
+
+Params:
+
+- `sessionId`: active RPC session ID.
+
+Returns identified-plugin actions with `id`, local `name`, `pluginId`,
+`description`, and strict object `schema`. Action IDs use
+`<plugin-id>/<action-name>`.
+
+### `pluginActions/run`
+
+Params:
+
+- `sessionId`: active RPC session ID.
+- `id`: complete namespaced action ID.
+- `arguments`: object matching the action schema; defaults to an empty object.
+
+Returns `action`, `output`, and a structured `result` with optional `message` and
+`data`. Actions run synchronously and therefore expose notifications and progress
+but not blocking questions, selections, confirmations, or input. They are
+rejected when the session execution profile disables plugin commands. Actions
+are intentionally not exposed in local slash completion; a plugin should also
+register a typed command when it needs a human-facing TUI entry point.
 
 ### `skills/captureSessions`, `skills/captureDraft`, and `skills/saveCapturedDraft`
 
@@ -884,4 +1021,5 @@ Returns login status for a login ID.
 - RPC is intended for a trusted local UI and can read/write files, run shell commands, update secrets, and use OAuth.
 - Workspace roots may be any existing local directory accessible to the process.
 - Tool execution matches current CLI behavior; mutating tools are not approval-gated by RPC.
+- `commands/run` and `pluginActions/run` execute trusted local plugin code. Action schemas validate data shape but are not an authorization boundary; use execution profiles to disable plugin operations for restricted sessions.
 - Responses and diagnostics redact secret-looking fields, but clients should still avoid logging full protocol traffic unless necessary.

data/doc/sandboxing.md

@@ -67,9 +67,12 @@ after changing the mode.
 
 An active worktree-backed tab uses a strict `workspace_write` policy for its
 model-requested command workers, regardless of the global `sandbox.mode` or
-`tools.workspace_guardrails` settings. The writable root is exactly the linked
-worktree and no configured additional writable roots are carried into the tab.
-The configured child-network setting is preserved.
+`tools.workspace_guardrails` settings. The default writable root is exactly the
+linked worktree and no configured additional writable roots are carried into the
+tab. When a workspace tool explicitly selects the verified `origin` target,
+Kward uses a separate strict command worker whose writable root is exactly that
+original worktree. Arbitrary target paths are not accepted. The configured
+child-network setting is preserved.
 
 If the current platform cannot provide filesystem enforcement, Kward refuses to
 activate the worktree instead of falling back to an unrestricted command
@@ -82,8 +85,11 @@ This does not contain the user-directed `/shell`, `!command`, `/capture`, or
 model-requested shell commands still cannot write Git metadata. Active worktree tabs additionally
 expose a narrow `git_commit` tool for explicit agent-requested commits; it runs
 through the trusted host-side Git workflow rather than widening the shell
-sandbox. The interactive `/git` flow remains available for manual review and
-commit.
+sandbox. The verified original worktree is available as `target: "origin"` on
+core workspace tools so an agent can inspect and resolve merge conflicts without
+switching tabs. Selecting that target does not add an approval layer; the normal
+configured tool-permission policy applies equally to both worktrees. The
+interactive `/git` flow remains available for manual review and commit.
 
 ## Platform support
 

data/doc/security.md

@@ -87,7 +87,7 @@ See [Lifecycle hooks](lifecycle-hooks.md) for policy examples and [RPC protocol]
 
 ## Opt-in permission policy
 
-`permissions.enabled` is off by default. When enabled, Kward can allow, ask, or deny model-requested file changes, shell commands, web tools, and MCP tools before execution. The interactive CLI uses an approval overlay; an unavailable approval bridge fails closed. The policy is not a sandbox: after Kward permits a shell command, it still runs with the permissions of your user account. See [Permissions](permissions.md) for workflows, modes, rules, and limits.
+`permissions.enabled` is off by default. When enabled, Kward can allow, ask, or deny model-requested file changes, shell commands, web tools, MCP tools, and plugin tools before execution. The interactive CLI uses an approval overlay; an unavailable approval bridge fails closed. The policy is not a sandbox: after Kward permits a shell command, it still runs with the permissions of your user account. See [Permissions](permissions.md) for workflows, modes, rules, and limits.
 
 ## Know what you are trusting
 
@@ -113,6 +113,11 @@ They can read files and environment variables, write files, run commands, and
 make network requests. Kward intentionally does not load plugins from a
 workspace directory.
 
+Identified-plugin configuration and state remain local to the active config
+directory. RPC capability reports include only plugin IDs and versions, never
+plugin configuration or secret values. Treat `host.logger` output as
+user-visible diagnostics and never write credentials to it.
+
 ### MCP servers
 
 Configured MCP servers are local child processes. Their tools can expose application state such as browser pages, console messages, network traffic, or screenshots. Kward currently supports local stdio servers, but local transport does not make an untrusted server safe.
@@ -168,6 +173,7 @@ Kward keeps user data under `~/.kward` by default, or mostly beside `KWARD_CONFI
 | Memory | `~/.kward/memory/` | Off by default; directory `0700` and files `0600`. |
 | Telemetry logs | `~/.kward/logs/` | Off by default; redacted metadata, not intentional prompt or file-content logging. |
 | Plugins | `~/.kward/plugins/` | Trusted Ruby code, not private data storage. |
+| Plugin state | `~/.kward/plugin_state/` | Namespaced by stable plugin ID; state files use mode `0600`. |
 | Hook audit log and trust records | `~/.kward/logs/`, `~/.kward/trusted_workspace_hooks.json` | Audit records use redacted metadata rather than raw event values. |
 
 Private file modes help on normal Unix-like systems but do not protect data from your own account, privileged users, backups, malware, or a compromised machine. Session exports are written to the path you choose and should be protected separately.

data/doc/session-management.md

@@ -25,13 +25,13 @@ To automatically resume the last active session for the current workspace on sta
 
 ## A normal session workflow
 
-Start a chat and give it a useful name:
+Start a chat and give the current session and tab a useful name:
 
 ```text
-/rename oauth cleanup
+/name oauth cleanup
 ```
 
-`/rename` requires a name. Use `/session name` without an argument to clear the current session name.
+`/name` requires a name and updates both the active session and its tab label. It can also be used while the active tab's agent is running; it is unavailable in plugin tabs. Use `/rename` when you only want to rename the session. Use `/session name` without an argument to clear the current session name.
 
 Work normally:
 
@@ -227,7 +227,8 @@ This is useful when you want to confirm which session you are in or check whethe
 | Need | Use |
 | --- | --- |
 | Continue earlier work | `/session` or `/resume` |
-| Give the current session a better name | `/rename <name>` |
+| Give the current session and tab a better name | `/name <name>` |
+| Give only the current session a better name | `/rename <name>` |
 | Clear the current session name | `/session name` |
 | Keep the current state but try another future | `/clone` |
 | Start a separate session from before an earlier prompt | `/fork` |

data/doc/tabs.md

@@ -59,11 +59,13 @@ Inspect, merge, or remove the binding explicitly:
 /tab worktree remove
 ```
 
-`/tab worktree merge` merges the active worktree's clean, committed branch directly into the branch currently checked out in its original workspace. Kward shows the source and target revisions and requires confirmation. Both worktrees must be clean. If Git reports conflicts, Kward leaves the original workspace in its normal merge state; resolve the conflicts there or cancel them with `/tab worktree merge abort`.
+`/tab worktree merge` merges the active worktree's clean, committed branch directly into the branch currently checked out in its original workspace. Kward shows the source and target revisions and requires confirmation. Both worktrees must be clean. If Git reports conflicts, Kward leaves the original workspace in its normal merge state while keeping the current tab on the linked branch. The composer shows the target branch and conflict count. Run `/tab worktree merge resolve` (or `/worktree merge resolve`) to start an agent turn that inspects and edits the verified original workspace with `target: "origin"`; the turn leaves committing for review. After the conflicts are resolved, run `/tab worktree merge continue` to stage the resolutions and complete the merge, or use `/tab worktree merge abort` to cancel it.
 
 Removal refuses a dirty worktree and keeps its branch. A worktree that is missing or no longer points at the recorded branch is restored as unavailable rather than silently falling back to the original workspace.
 
-Worktree tabs are available for normal session tabs, not plugin-owned tabs. Kward's file tools, `@`/`$` completion, `/files` browser, integrated editor, and model-requested shell workers use the active worktree root. Model operations retain strict workspace guardrails. The user-directed `/shell`, `!command`, `/capture`, and `/pty` features remain host-process operations and are not contained by the model command sandbox; use them only when that is intentional. Generic shell Git writes remain protected. When explicitly asked to commit, the agent can use the active tab's narrow `git_commit` tool; use the interactive `/git` flow when you want to review and commit changes yourself.
+Worktree tabs are available for normal session tabs, not plugin-owned tabs. Kward's file tools, `@`/`$` completion, `/files` browser, integrated editor, and model-requested shell workers use the active worktree root by default. Core model workspace tools advertise an optional `target` selector in an active worktree tab: `active` keeps the normal linked-worktree root, while `origin` selects only that tab's verified original repository worktree. Selecting `origin` does not add a separate approval prompt; the normal configured tool-permission policy applies equally to both targets. Paths remain relative to the selected root, and arbitrary filesystem targets are never accepted.
+
+Both targets retain strict workspace guardrails and separate command sandboxes. The user-directed `/shell`, `!command`, `/capture`, and `/pty` features remain host-process operations and are not contained by the model command sandbox; use them only when that is intentional. Generic shell Git writes remain protected. When explicitly asked to commit, the agent can use `git_commit` for the active worktree or set `target: "origin"` for the original worktree; use the interactive `/git` flow when you want to review and commit changes yourself.
 
 ## Common workflow
 
@@ -98,6 +100,8 @@ Tabs keep the conversations separate, so context from one tab does not automatic
 | `/tab worktree detach` | Return to the original workspace while keeping the linked worktree and branch |
 | `/tab worktree status` | Show the current tab's worktree binding and Git status |
 | `/tab worktree merge` | Merge the current worktree branch into the branch checked out in its original workspace |
+| `/tab worktree merge resolve` | Ask the agent to resolve an in-progress merge in the original workspace from the same tab |
+| `/tab worktree merge continue` | Stage resolutions and complete an in-progress merge after confirmation |
 | `/tab worktree merge abort` | Abort a conflicted worktree merge in the original workspace |
 | `/tab worktree remove` | Remove a clean linked worktree and keep its branch |
 | `/worktree …` | Alias for `/tab worktree …` on the active tab |

data/doc/transports.md

@@ -104,6 +104,13 @@ Plugin-chat drivers may accept a `context:` keyword on `submit`. Transport turns
 provide the authenticated actor there. Existing drivers that do not accept the
 keyword continue to work, but cannot use actor-specific context.
 
+The plugin-chat factory host reports `surface: :transport`, the stable chat type
+ID and scope key, immutable plugin configuration, scoped durable storage, secret
+lookup, logging, declared chat capabilities, and managed cleanup. Storage is
+isolated by plugin, chat type, and external conversation scope. Versioned chat
+contracts also reject attachments not declared by that chat type before calling
+the driver.
+
 Plugin-chat transport IDs, turn events, transcript storage, and authorization
 remain separate from normal workspace sessions. A plugin's `singleton: :global`
 setting also means that all transport conversations share that one plugin
@@ -119,6 +126,14 @@ API.
 Transports that cannot support interactive approvals must use an explicit
 configured fallback policy; they must not leave an agent turn waiting forever.
 
+Structured plugin UI requests use the same transport-neutral interaction path.
+Plugin `question`, `select`, `confirm`, and `input` calls arrive with matching
+interaction kinds, prompts, choices, and metadata, and answers are routed back to the
+waiting plugin handler. An adapter may support only a subset, but it must cancel
+or answer unsupported requests rather than leaving the turn blocked. Plugin
+notifications and progress remain local to the RPC/TUI UI bridge for now and
+are not transport interaction requests.
+
 ## Storage and routing
 
 Transport plugins receive namespaced durable storage for state such as:

data/doc/usage.md

@@ -136,11 +136,14 @@ Slash commands run local actions in the current session. Most do not send a prom
 | `/tab close` | close the active tab. |
 | `/tab new` | open a new tab. |
 | `/tab name <label>` | rename the active tab label. |
+| `/name <name>` | rename the active session and tab together; available while the tab's agent is running. |
 | `/tab worktree` | create or activate the active session tab's linked Git worktree. |
 | `/tab worktree activate` | explicitly create or activate the active session tab's linked Git worktree. |
 | `/tab worktree detach` | return to the original workspace while keeping the linked worktree and branch. |
 | `/tab worktree status` | inspect the active tab's worktree binding and changes. |
 | `/tab worktree merge` | merge a clean worktree branch into the branch checked out in its original workspace. |
+| `/tab worktree merge resolve` | ask the agent to resolve an in-progress merge in the original workspace from the same tab. |
+| `/tab worktree merge continue` | stage resolutions and complete an in-progress merge after confirmation. |
 | `/tab worktree merge abort` | abort a conflicted worktree merge in the original workspace. |
 | `/tab worktree remove` | remove a clean linked worktree while keeping its branch. |
 | `/worktree …` | alias for `/tab worktree …` on the active tab. |
@@ -191,7 +194,7 @@ Use sessions when work spans more than one terminal sitting, or when you want to
 Typical flow:
 
 ```text
-/rename oauth cleanup
+/name oauth cleanup
 # work with Kward
 /export oauth-notes.md
 /exit

data/doc/workspace-tools.md

@@ -21,6 +21,15 @@ Important behavior:
 - Edits use exact text replacement, so accidental partial or fuzzy changes fail instead of guessing.
 - With sandboxing off (the default), shell commands run as your operating-system user from the workspace. Enable [command sandboxing](sandboxing.md) to apply an OS boundary to model-requested `run_shell_command` workers. Command output is capped at 128 KB.
 
+### Worktree targets
+
+In an active linked-worktree tab, `list_directory`, `read_file`, `write_file`, `edit_file`, `run_shell_command`, `summarize_file_structure`, and `context_for_task` also advertise an optional `target` argument:
+
+- `active` is the default linked worktree.
+- `origin` is the tab's verified original repository worktree.
+
+Kward supplies this fixed role map from the tab binding; the model cannot provide an arbitrary filesystem root. Selecting `origin` does not add a separate approval prompt, so the agent can complete a requested inspect/edit/test/commit workflow without interruption. The normal configured tool-permission policy still applies equally to both targets. Each target keeps its own path guard and strict shell sandbox.
+
 ## Reading the workspace
 
 ### `list_directory`

data/examples/plugins/space_invaders.rb

@@ -15,7 +15,7 @@
 # The game renders colored sprites and particle-burst explosions inside the
 # composer canvas region using the interactive mode API.
 
-Kward.plugin do |plugin|
+Kward.plugin(id: "com.kward.example.space-invaders", version: "1.0.0", api: 1) do |plugin|
   plugin.interactive_command "invaders", rows: 18, fps: 30, description: "Space Invaders arcade game" do |ui, ctx|
     game = SpaceInvadersGame.new(width: ui.width, height: ui.height)
     ui.on_tick { |ui| game.tick(ui) }

data/examples/plugins/stardate_footer.rb

@@ -1,6 +1,6 @@
 # Displays the current Federation stardate in Kward's interactive footer.
-Kward.plugin do |plugin|
-  plugin.footer do |_ctx|
+Kward.plugin(id: "com.kward.example.stardate-footer", version: "1.0.0", api: 1) do |plugin|
+  plugin.status "stardate", priority: :low do |_ctx|
     now = Time.now.utc
     reference = Time.utc(1987, 7, 15)
     stardate = 41_000 + ((now - reference) / (365.25 * 24 * 60 * 60) * 1_000)

data/examples/plugins/telegram/plugin.rb

@@ -1,6 +1,6 @@
 require_relative "telegram_transport"
 
-Kward.plugin do |plugin|
+Kward.plugin(id: "com.kward.telegram", version: "1.0.0", api: 1) do |plugin|
   capabilities = {
     inbound: %i[text],
     outbound: %i[text],

data/lib/kward/agent.rb

@@ -3,6 +3,7 @@ require_relative "model/chat_invocation"
 require_relative "compactor"
 require_relative "model/context_overflow"
 require_relative "conversation"
+require_relative "plugins/turn_request"
 require_relative "events"
 require_relative "deep_copy"
 require_relative "hooks"
@@ -41,9 +42,9 @@ module Kward
 
     attr_reader :conversation, :tool_registry
 
-    # Adds a user message, compacts context when needed, and runs the turn.
+    # Adds user input or scopes a plugin system request, then runs a normal turn.
     #
-    # @param input [String] text sent to the model
+    # @param input [String, PluginTurnRequest] user text or host-staged system instructions
     # @param display_input [String, nil] alternate text kept for transcripts
     # @yieldparam event [Object] streamed turn event for frontends
     # @return [String] final assistant answer
@@ -52,19 +53,31 @@ module Kward
       status = "completed"
       error = nil
       cancellation&.raise_if_cancelled!
-      turn_start = run_hook("turn_start", payload: { input: input, display_input: display_input })
+      system_turn = input if input.is_a?(PluginTurnRequest)
+      display_input ||= system_turn.to_s if system_turn
+      input = system_turn.system if system_turn
+      turn_start = run_hook("turn_start", payload: { input: input, display_input: display_input, input_role: system_turn ? "system" : "user" })
       return hook_denied_answer(turn_start) if turn_start.denied?
 
       input = turn_start.payload[:input] || turn_start.payload["input"] || input
       display_input = turn_start.payload[:display_input] || turn_start.payload["display_input"] || display_input
-      @conversation.refresh_system_message_if_workspace_agents_changed!
-      @conversation.append_user(input, display_content: display_input)
-      run_hook("turn_context_build_before", payload: { message_count: @conversation.messages.length })
-      auto_compact_if_needed
-      run_hook("turn_context_build_after", payload: { message_count: @conversation.messages.length })
-      answer = run_turn(on_reasoning_delta: on_reasoning_delta, on_retry: on_retry, cancellation: cancellation, steering: steering, options: options, tool_registry: tool_registry, &block)
-      run_hook("turn_end", payload: { input: input, answer: answer })
-      answer
+      if system_turn
+        system_turn = PluginTurnRequest.new(system: input, command: system_turn.command, plugin_id: system_turn.plugin_id, id: system_turn.id)
+      end
+      @conversation.with_system_turn(system_turn) do
+        @conversation.refresh_system_message_if_workspace_agents_changed!
+        if system_turn
+          @conversation.append_system_turn(system_turn)
+        else
+          @conversation.append_user(input, display_content: display_input)
+        end
+        run_hook("turn_context_build_before", payload: { message_count: @conversation.messages.length })
+        auto_compact_if_needed
+        run_hook("turn_context_build_after", payload: { message_count: @conversation.messages.length })
+        answer = run_turn(on_reasoning_delta: on_reasoning_delta, on_retry: on_retry, cancellation: cancellation, steering: steering, options: options, tool_registry: tool_registry, &block)
+        run_hook("turn_end", payload: { input: input, answer: answer })
+        answer
+      end
     rescue StandardError => e
       status = "failed"
       error = e

data/lib/kward/cli/compaction.rb

@@ -6,7 +6,7 @@ module Kward
     module CompactionCommands
       private
 
-      def compact_context(agent, argument)
+      def compact_context(agent, argument, cancellation: nil)
         before = run_lifecycle_hook("session_compact_before", conversation: agent.conversation, payload: { instructions: argument.to_s })
         if before.denied? || before.approval_required?
           runtime_output("Declined: #{before.decision.message || "session compaction denied"}")
@@ -17,16 +17,22 @@ module Kward
           conversation: agent.conversation,
           client: @client,
           tool_result_summarizer: lambda { |tool_call, content| tool_result_summary(tool_call, content) }
-        ).compact(custom_instructions: argument)
+        ).compact(custom_instructions: argument, cancellation: cancellation)
         run_lifecycle_hook("session_compact_after", conversation: agent.conversation, payload: { old_message_count: result.old_message_count, new_message_count: result.new_message_count })
         runtime_output("Compacted context: #{result.old_message_count} messages -> #{result.new_message_count} messages.")
-        render_transcript_block("Assistant", result.summary)
+        result.summary
       rescue Compactor::NothingToCompact, Compactor::AlreadyCompacted, Compactor::EmptySummary => e
         runtime_output(e.message)
+      rescue Cancellation::CancelledError
+        raise
       rescue StandardError => e
         runtime_output("Compaction error: #{e.message}")
       end
 
+      def render_compaction_summary(summary)
+        render_transcript_block("Assistant", summary)
+      end
+
     end
   end
 end