kward 0.83.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

@@ -2,7 +2,7 @@
 
 Kward can read code, edit files, run commands, call model and search providers, and load local extensions. That makes it useful, but it also means you should treat it like a developer tool running with your account—not like a sandbox.
 
-This guide explains the trust boundaries and gives you a safe way to start work in an unfamiliar repository.
+This guide explains the trust boundaries and gives you a safe way to start work in an unfamiliar repository. Report suspected vulnerabilities privately through the [security policy](https://github.com/kaiwood/kward/blob/main/SECURITY.md).
 
 ## The short version
 
@@ -56,7 +56,8 @@ Kward's built-in file tools normally resolve paths inside the active workspace.
 
 These protections reduce accidental edits. They do not contain the whole process:
 
-- With `sandbox.mode: off` (the default), `run_shell_command`, `!command`, `/capture`, `/shell`, and `/pty` run with your user permissions.
+- With `sandbox.mode: off` (the default), `run_shell_command`, `!command`, `/capture`, `/shell`, `/pty`, and editor buffer runners run with your user permissions.
+- Editor buffer runners are user-directed and execute the current in-memory buffer, including normal files and scratchpads, through the configured `editor.runners` binary without a shell. They are not covered by the command sandbox.
 - A non-off [command sandbox](sandboxing.md) restricts only model-requested `run_shell_command` workers and their descendants. It does not cover `!command`, `/capture`, `/shell`, or `/pty`, including commands that the transient `?` shell assistant runs through the user's persistent `/shell` process.
 - External `/shell` commands, `!command`, and `/pty` receive an interactive PTY. Kward forwards a conservative set of line-oriented controls into the inline region, then grants full-terminal passthrough when a child emits screen-oriented or unknown controls. Full passthrough bypasses transcript control-sequence sanitization, so run only commands you trust with terminal access. `capture <command>` and `/capture <command>` sanitize their captured output.
 - Plugins, command hooks, and MCP servers are local processes with the same general operating-system access.
@@ -86,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
 
@@ -112,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.
@@ -167,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/shell.md

@@ -23,13 +23,12 @@ The command runs from the active workspace root and begins in an inline PTY regi
 
 When an inline command exits without reading input, safe output is mirrored into the transient transcript view so a repaint cannot hide it. Carriage-return and horizontal-cursor progress redraws are reduced to their final visible lines, while an unterminated synchronized-output update is closed before Kward redraws. If the child reads input, Kward retains only output captured before the first forwarded input byte; this prevents echoed passwords, OTPs, or other input from entering tab state. Output from one-off commands is never added to the AI conversation or sent to the model.
 
-Shell output can leave transient text in the transcript area. **After the command finishes, press Ctrl+L to redraw the durable conversation and clear that transient `!command` output.** While an interactive command is still running, the composer remains frozen and keyboard input—including Ctrl+L and Kward's tab shortcuts—belongs to the child process.
+Shell output can leave transient text in the transcript area. **After the command finishes, press Ctrl+L to redraw the durable conversation and clear that transient `!command` output.** While an interactive command owns the terminal, the composer remains frozen and ordinary keyboard input belongs to the child process. Kward's tab shortcuts are intercepted separately; switching tabs detaches the command and lets it continue in the originating tab's bounded background state.
 
-Configured `ekwsh.yml` aliases also work after `!`:
+Configured `kwshrc` aliases also work after `!`:
 
-```yaml
-aliases:
-  glog: "git log --decorate --stat --graph"
+```sh
+alias glog='git log --decorate --stat --graph'
 ```
 
 ```text
@@ -38,9 +37,8 @@ aliases:
 
 An alias that resolves to `kward edit <filename>` opens Kward's integrated editor in the current session instead of starting a nested Kward process:
 
-```yaml
-aliases:
-  vibe: "kward edit"
+```sh
+alias vibe='kward edit'
 ```
 
 ```text
@@ -112,6 +110,8 @@ If you explicitly ask the assistant to change shell state, it can use the active
 
 For a suggestion or prepared command, the assistant uses `prepare_shell_command`. The command is placed in the shell composer but is not run until you press `Enter`. Running a command directly and preparing one are deliberately separate actions.
 
+If you explicitly ask it to open an existing workspace file, the assistant uses `open_editor` to open Kward's integrated editor. Opening the editor does not modify or save the file.
+
 The shell assistant cannot safely run commands that require terminal input. Ask it to prepare those commands instead. The local `/shell` session keeps one interactive shell process alive, so directory changes, variables, functions, aliases, and other shell state persist between commands. The one-off `!command` and `/capture` workflows remain separate. SSH remains available through the normal interactive PTY handoff, but shell-agent prompting resumes after that SSH session exits.
 
 ## Interactive and captured commands
@@ -131,13 +131,13 @@ Use `capture` inside `/shell` when you want ordinary, readable output in Kward's
 
 ```sh
 capture git status --short
-capture bundle exec ruby -Itest test/test_ekwsh.rb
+capture bundle exec ruby -Itest test/test_kwsh.rb
 ```
 
-An `ekwsh` `capture` command:
+An `kwsh` `capture` command:
 
 - does not receive keyboard input,
-- uses the timeout and output-size limit from `ekwsh.yml`,
+- uses kwsh's built-in timeout and output-size limits,
 - preserves safe color and styling,
 - strips controls that could corrupt Kward's TUI,
 - can be cancelled with Ctrl+C.
@@ -163,9 +163,9 @@ Each Kward tab owns its `/shell` state. Switching away and back restores that ta
 - runtime aliases,
 - shell prompt and transcript view.
 
-Shell commands use a separate, workspace-scoped history rather than the normal chat-prompt history. Configure its size with `history_limit` in `ekwsh.yml`.
+Shell commands use a separate, workspace-scoped history rather than the normal chat-prompt history. The shell-history limit is a built-in kwsh default.
 
-Kward's tab shortcuts work at the shell prompt and while a captured command is running. During an interactive command, the child owns every key; exit or interrupt it before switching Kward tabs. Bounded output from shell-agent `?` turns is also retained in the tab's transient runtime view, so it is restored when you switch away and back without being added to session history. Ctrl+L clears this transient shell and shell-agent output.
+Kward's tab shortcuts work at the shell prompt and while a shell command is running. Switching tabs detaches the running command instead of interrupting it; bounded output and completion state remain owned by the originating tab and are restored when you return. While detached, the command no longer receives terminal input. Explicit cancellation or shutdown still terminates detached work. Bounded output from shell-agent `?` turns is also retained in the tab's transient runtime view, so it is restored when you switch away and back without being added to session history. Ctrl+L clears this transient shell and shell-agent output.
 
 ## Completion
 
@@ -210,6 +210,7 @@ The persistent `/shell` process handles these commands in-session so their state
 | `cd [dir]` | Change the shell directory. Supports `cd`, `cd -`, and relative paths. |
 | `pwd` | Print the shell directory. |
 | `export KEY[=value]` | Set an environment variable. `export` and `export -p` list variables. |
+| `source <file>` / `. <file>` | Parse and apply aliases and exports from an rc file immediately. |
 | `unset KEY` | Remove an environment variable. |
 | `alias [name]` | List, inspect, or create aliases. |
 | `unalias name` / `unalias -a` | Remove aliases. |
@@ -220,39 +221,56 @@ The persistent `/shell` process handles these commands in-session so their state
 
 Built-ins take precedence over aliases and executables.
 
-## Configure ekwsh
+## Configure kwsh
 
-Global shell configuration lives at:
+Global shell configuration lives in these optional rc files, loaded in order:
 
 ```text
-~/.kward/ekwsh.yml
+~/.kward/kwshrc
+~/.kwshrc
 ```
 
-When `KWARD_CONFIG_PATH` selects another main config file, Kward reads `ekwsh.yml` from the same directory.
+When `KWARD_CONFIG_PATH` selects another main config file, Kward reads the first file beside that config file instead. The later file overrides earlier aliases and exported variables with the same names. The rc format currently supports declarative `alias`, `export`, and `source` directives:
 
-A practical configuration might look like this:
+```sh
+alias ll='ls -la'
+alias gs="git status --short"
+export BUNDLE_WITHOUT=production
+export PATH="$HOME/bin:$PATH"
+source ~/.kward/kwsh-aliases
+```
 
-```yaml
-shell: /bin/sh
-timeout_seconds: 300
-max_output_bytes: 1048576
-history_limit: 1000
+`source` reads another rc file without executing it; relative paths in rc-file directives are resolved from the file containing the directive. When entered as a `/shell` builtin, the path is resolved from the current shell directory and its aliases and exports are applied immediately, without restarting Kward. Unsupported shell scripting is ignored for now.
 
-env:
-  FORCE_COLOR: "1"
-  BUNDLE_WITHOUT: "production"
-  RAILS_ENV: "test"
+The transient shell assistant normally follows the active conversation's model and reasoning effort. Configure it in the main JSON file:
 
-aliases:
-  ll: "ls -la"
-  gs: "git status --short"
-  gd: "git diff --color=always"
-  glog: "git log --decorate --stat --graph"
-  be: "bundle exec"
-  t: "bundle exec ruby -Itest"
+```json
+{
+  "shell": {
+    "agent": {
+      "provider": "openrouter",
+      "model": "openai/gpt-5.6-sol",
+      "reasoning_effort": "none"
+    }
+  }
+}
 ```
 
-### Settings
+The optional `provider` uses the lowercase configuration IDs listed in [Model providers](providers.md). When omitted, the shell assistant follows the active conversation. If a provider is explicitly configured without a model or reasoning effort, Kward uses that provider's defaults instead of inheriting the active conversation's values.
+
+Override those settings with environment variables:
+
+```sh
+export KWSH_PROVIDER="openrouter"
+export KWSH_MODE="openai/gpt-5.6-sol"
+export KWSH_REASONING="none"
+```
+
+Environment variables take precedence over the JSON settings, and empty values are ignored.
+
+### Runtime defaults
+
+These runtime settings are built into kwsh and are not configurable through rc files:
 
 | Setting | Default | What it does |
 | --- | --- | --- |
@@ -265,14 +283,14 @@ Invalid or relative `shell` paths fall back to `/bin/sh`. These timeout and outp
 
 ### Environment
 
-Configured `env` values are applied when `/shell` starts. Keys must be valid environment-variable names; nil values and invalid keys are ignored, and other values are converted to strings.
+`export` values from rc files are applied when `/shell` starts and are also available to leading-`!` commands. Keys must be valid environment-variable names; invalid keys are ignored. Values support shell quoting and simple `$VAR`/`${VAR}` expansion.
 
 Kward also supplies conservative terminal defaults:
 
 ```sh
-CLICOLOR=1
-COLORTERM=truecolor
-TERM=xterm-256color  # only when TERM is missing or dumb
+export CLICOLOR=1
+export COLORTERM=truecolor
+export TERM=xterm-256color  # only when TERM is missing or dumb
 ```
 
 It does not force color. Set `FORCE_COLOR`, `CLICOLOR_FORCE`, or a command-specific option such as `--color=always` when needed.
@@ -283,18 +301,17 @@ When rbenv is available, Kward adds its shims and bin directories to `PATH` and
 
 Aliases replace the first command word once and append any remaining arguments:
 
-```yaml
-aliases:
-  ll: "ls -la"
-  t: "bundle exec ruby -Itest"
+```sh
+alias ll='ls -la'
+alias t='bundle exec ruby -Itest'
 ```
 
 ```sh
 ll lib
 # runs: ls -la lib
 
-t test/test_ekwsh.rb
-# runs: bundle exec ruby -Itest test/test_ekwsh.rb
+t test/test_kwsh.rb
+# runs: bundle exec ruby -Itest test/test_kwsh.rb
 ```
 
 Configured aliases work inside `/shell` and after `!`. Aliases created with the `alias` built-in belong only to the current `/shell` session and are not shared with one-shot `!command` input.

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 |