kward 0.77.0 → 0.79.0

data/doc/permissions.md

@@ -0,0 +1,180 @@
+# Permissions
+
+Kward's permission policy lets you put a human decision between a model-requested tool call and its side effect. It is useful when you want the agent to inspect a project freely, but want to confirm edits, commands, web requests, or MCP calls as they arise.
+
+Permissions are **off by default**. Enabling them does not sandbox Kward or its subprocesses: an allowed shell command still runs with your operating-system user permissions unless you separately enable [command sandboxing](sandboxing.md) for model-requested shell commands.
+
+## Start with approval mode
+
+Add this to `~/.kward/config.json`, or enable it through your usual configuration workflow:
+
+```json
+{
+  "permissions": {
+    "enabled": true,
+    "mode": "ask"
+  }
+}
+```
+
+In `ask` mode, Kward allows ordinary read-only tools and asks before the agent:
+
+- writes or edits a workspace file,
+- runs `run_shell_command`,
+- searches or fetches content on the web,
+- calls an MCP tool.
+
+When approval is required in the interactive CLI, Kward opens a modal overlay. It shows the complete tool arguments, so an approval for `read_skill` includes the requested skill name and relative path, and an approval for a write includes its path and content. Choose **Allow once** to run that one call, **Allow this tool for this session** to allow later calls to the same tool in the current Kward session, or **Deny** to stop it. Pressing `Esc`, cancelling the overlay, or losing the approval bridge denies the call.
+
+### Steer the agent with `Type something`
+
+**Type something** is more than a denial. It stops the requested tool call and sends your text back to the agent as the tool result, so you can redirect its workflow without waiting for it to finish a wrong turn.
+
+For example, the agent may propose this command:
+
+```text
+run_shell_command: grep -R "Permission" lib test
+```
+
+Choose **Type something** and enter:
+
+```text
+Use ack instead of grep; it is installed here and respects our ignore files.
+```
+
+Kward does not run `grep`. The agent receives:
+
+```text
+Declined: Use ack instead of grep; it is installed here and respects our ignore files.
+```
+
+It can then continue by choosing an `ack` command. This is useful for steering details that are difficult to encode in a static rule, such as:
+
+- use the project’s preferred formatter or test runner;
+- run a focused test rather than the full suite;
+- use a local mirror or a documented API endpoint;
+- explain a proposed database command before running it;
+- choose an existing project script instead of inventing a new command.
+
+The typed response is part of the conversation, just like a normal follow-up message. It is stored in the session and may be sent to the active model provider. Do not put secrets in it unless that is acceptable for your selected provider and retained session data.
+
+Use this mode first when working in an unfamiliar repository or when you want to review an agent's actions without preventing ordinary exploration.
+
+## Choose a mode
+
+Set `permissions.mode` to one of these values:
+
+| Mode | Good for | Default behavior |
+| --- | --- | --- |
+| `ask` | Interactive supervised work | Asks before file changes, shell commands, web tools, and MCP tools. |
+| `workspace-write` | Routine edits in selected paths | Allows file changes in `write_scopes`; still asks before shell, web, and MCP tools. |
+| `read-only` | Code review and investigation | Denies risky tools by default. |
+| `deny-by-default` | Automation or tightly controlled runs | Denies risky tools unless an `allow` rule matches. |
+
+All modes leave ordinary read-only Kward tools available. Rules can make a decision more specific; see [Rules and precedence](#Rules_and_precedence).
+
+## Let Kward edit only selected paths
+
+Use `workspace-write` when you want routine changes in known source and test directories without an approval prompt for each edit:
+
+```json
+{
+  "permissions": {
+    "enabled": true,
+    "mode": "workspace-write",
+    "write_scopes": ["lib/**", "test/**"]
+  }
+}
+```
+
+With this configuration, the agent may edit `lib/` and `test/` without asking. A proposed edit to `README.md` or `config/` is denied by the policy.
+
+`write_scopes` narrows the policy's default workspace-write behavior; it does not broaden Kward's built-in workspace boundary. File tools still stay inside the active workspace by default, and existing files must still be read before Kward can edit them. See [Workspace tools](workspace-tools.md) for those guardrails.
+
+An empty `write_scopes` array permits no default workspace writes. Omit `write_scopes` if you want the `workspace-write` mode to cover the normal workspace file-tool boundary.
+
+## Rules and precedence
+
+Use `allow`, `ask`, and `deny` arrays to describe exceptions. A rule can match these fields:
+
+- `tool` — a model tool name, such as `run_shell_command` or `write_file`;
+- `path` — the file-tool path supplied by the model;
+- `command` — the requested shell command text;
+- `host` — the host in a `fetch_content` or `fetch_raw` URL;
+- `source` — currently useful for `mcp` tools.
+
+Patterns support `*` within a path segment and `**` across directories. Rule matching is case-sensitive.
+
+```json
+{
+  "permissions": {
+    "enabled": true,
+    "mode": "ask",
+    "allow": [
+      { "tool": "write_file", "path": "doc/**" },
+      { "tool": "fetch_content", "host": "docs.ruby-lang.org" }
+    ],
+    "ask": [
+      { "tool": "run_shell_command", "command": "bundle exec *" }
+    ],
+    "deny": [
+      { "tool": "run_shell_command", "command": "git push*" },
+      { "tool": "write_file", "path": "**/.env" }
+    ]
+  }
+}
+```
+
+Kward evaluates matching rules in this order:
+
+1. `deny`
+2. `ask`
+3. `allow`
+4. the selected mode's default
+
+A matching deny always wins. An ask rule wins over an allow rule. Keep rules narrow and easy to explain; prefer an exact command or a small path scope over a broad wildcard.
+
+## A practical workflow
+
+For a normal coding task:
+
+1. Enable `ask` mode.
+2. Ask Kward to inspect the project and propose a change.
+3. Approve the file edit after checking its path and intent.
+4. Approve a focused test command, or choose **Type something** to redirect it—for example, “run `bin/test unit` instead of the full suite.”
+5. Review the diff and `git status` as usual.
+
+If you repeatedly work in one source tree, move to `workspace-write` with narrow write scopes. Keep shell and network calls in approval mode unless you have a well-understood policy for them.
+
+## RPC and Pan
+
+RPC clients can continue to use the existing per-turn approval bridge:
+
+```json
+{
+  "approvalMode": "ask"
+}
+```
+
+That requests an approval notification for every tool call in that turn. The global permission policy is an additional restriction: a deny rule prevents the call even if the RPC client would approve it. If the global policy requires approval, a frontend without an approval bridge fails closed.
+
+Pan currently has no dedicated approval interface. With permissions enabled, a Pan session cannot approve a policy `ask` decision, so Kward denies it. Use `read-only`, explicit allows, or a CLI/RPC frontend when approvals are needed.
+
+## Limits: policy is not a sandbox
+
+The policy runs before Kward dispatches a model-requested tool. It does not constrain what happens after a shell command starts. In particular:
+
+- a permitted shell command can access files, processes, credentials, and network services available to your user account;
+- command-text rules are useful review controls, not a reliable way to enforce network destinations or all subprocess behavior;
+- direct commands that you type yourself—`!command`, `/shell`, and `/pty`—are treated as your actions and are outside this first policy scope;
+- plugins, hooks, and MCP servers are trusted local extensions with their own process access.
+
+For sensitive work, use a restricted operating-system account, container, virtual machine, or disposable checkout. [Command sandboxing](sandboxing.md) is a separate, opt-in operating-system boundary for model-requested `run_shell_command` workers. It can add filesystem and child-network restrictions, but does not cover Kward's host process, extensions, or direct interactive commands.
+
+## Related guides
+
+- [Security and trust](security.md): trust boundaries, extensions, and safe work in unfamiliar repositories.
+- [Configuration](configuration.md#Permissions): the complete configuration reference.
+- [Command sandboxing](sandboxing.md): configure the separate OS boundary for model-requested shell commands.
+- [Lifecycle hooks](lifecycle-hooks.md): add trusted local policy or automation around Kward events.
+- [RPC protocol](rpc.md#Tool_approval_bridge): implement the approval bridge in an RPC client.

data/doc/plugins.md

@@ -178,6 +178,64 @@ Returning `:exit` from the tick callback ends the loop, same as calling
 Interactive commands require the TUI prompt interface. They are not available
 in piped/non-interactive mode or through RPC.
 
+## Add a plugin-owned tab
+
+A plugin can provide a persistent tab with Kward's normal composer, transcript
+rendering, streaming, image input, cancellation, and tab switching. The plugin
+owns its transcript, storage, model behavior, and any global state; it does not
+need to use a Kward workspace session.
+
+```ruby
+Kward.plugin do |plugin|
+  plugin.tab_type "example", id: "com.example.chat", title: "Example", singleton: :global do |host, descriptor|
+    ExampleChat.new(client: host.client, descriptor: descriptor)
+  end
+end
+```
+
+Open it from interactive Kward:
+
+```text
+/tab open example
+```
+
+`id` is a stable persisted identifier: do not change it after release.
+Use `singleton: :global` for one plugin-managed chat shared by all tab views.
+
+Plugin tabs do not notify global transcript observers by default. Set
+`transcript_events: true` only when the tab explicitly permits its streamed
+content to be delivered to every installed `on_transcript_event` handler, such
+as a local text-to-speech plugin:
+
+```ruby
+plugin.tab_type "example", id: "com.example.chat", transcript_events: true do |host, descriptor|
+  ExampleChat.new(client: host.client, descriptor: descriptor)
+end
+```
+
+The observer context exposes the plugin tab's `messages` through
+`ctx.transcript.messages`; it has no workspace session. The tab driver returned by the block must provide:
+
+- `messages` — renderable transcript messages;
+- `submit(input, display_input:, cancellation:, steering:)` — a turn method
+  that returns the final response and yields stream events;
+- `descriptor` — the durable tab descriptor;
+- `supports_steering?` and `assistant_label`.
+
+A driver may optionally implement `handles_command?(input)` and
+`handle_command(input)` for its own slash commands. Other Kward session and
+workspace commands stay unavailable inside plugin tabs.
+
+Set `rpc: true` when the plugin tab can also be exposed as a trusted local RPC chat:
+
+```ruby
+plugin.tab_type "example", id: "com.example.chat", rpc: true do |host, descriptor|
+  ExampleChat.new(client: host.client, descriptor: descriptor)
+end
+```
+
+RPC clients discover opted-in types through `initialize.capabilities.pluginChats`, open a chat with `pluginChats/open`, and must explicitly subscribe before receiving live `pluginChat/event` notifications. See [RPC](rpc.md) for the protocol. Plugin tabs remain CLI-only unless they opt in.
+
 ## Observe transcript events
 
 Use transcript events when you need to log or react to live activity:

data/doc/releasing.md

@@ -1,6 +1,6 @@
 # Releasing Kward
 
-Kward requires Ruby >= 3.2 (`spec.required_ruby_version` in `kward.gemspec`). If you develop with a newer Ruby, verify tests pass against the minimum supported version before releasing.
+Kward requires Ruby >= 3.4 (`spec.required_ruby_version` in `kward.gemspec`). If you develop with a newer Ruby, verify tests pass against the minimum supported version before releasing.
 
 Release steps before publishing:
 

data/doc/rpc.md

@@ -52,6 +52,7 @@ Detailed capability fields include:
 - `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, supported session methods, startup auto-resume capability/default, immediate transcript support for auto-resume, RPC list support, active live-session discovery, supported linear-session fork methods, supported compaction, supported tree navigation with labels and branch summarization, explicit unsupported import support, and unsupported live session updates reported with `notification: "session/updated"`.
 - `turns`: async turn mode, per-session concurrency, active/recent turn listing, provider-gated native busy-input steering, queued follow-up input, best-effort cancellation, recent in-memory event replay behavior, per-turn options for model/reasoning/tool scope/tool approval, and 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.
 - `events`: `turn/event` notification details, assistant/reasoning event names, normalized tool metadata, tool update/result events, diff result support, configured workspace guardrail status, focused context and context-budget stats tool support, and explicit unsupported shell changed-file detection/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/reasoning RPC methods, explicit OpenRouter catalog listing, exposed model fields, and no scoped model support.
@@ -61,11 +62,12 @@ Detailed capability fields include:
 - `auth`: Kward auth provider format, OpenAI and Anthropic OAuth, OpenRouter API-key login, GitHub/Copilot status reporting, and provider logout for stored credentials. GitHub OAuth login is CLI-only; RPC reports `supported: false` for the GitHub provider with a reason string.
 - `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.
+- `skillCapture`: capture a reviewed personal `SKILL.md` from any saved session’s active branch through `skills/captureSessions`, `skills/captureDraft`, and `skills/saveCapturedDraft`.
 - `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`. MCP resources, prompts, sampling, and Streamable HTTP are explicitly unsupported for now.
 - `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.
 - `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.
-- `security`: trusted-local behavior with optional per-turn tool approval. By default there is no workspace mutation guard or tool approval and shell/file mutation can run. File-tool workspace guardrails are reported under `capabilities.events.tools.workspaceGuardrails` and `runtime/state.workspaceGuardrailsEnabled`.
+- `security`: trusted-local behavior with optional per-turn tool approval. By default there is no workspace mutation guard or tool approval and shell/file mutation can run. File-tool workspace guardrails are reported under `capabilities.events.tools.workspaceGuardrails` and `runtime/state.workspaceGuardrailsEnabled`. `security.sandbox` reports the configured command-worker sandbox mode, enforcement backend, filesystem/network capability, and explicitly unsupported session pinning and one-time elevation. See [Command sandboxing](sandboxing.md) for its scope and limits.
 - `export`: supported transcript export formats. Currently `markdown` and `html`; default is `markdown`.
 - `starterPack`: explicitly unsupported (`supported: false`, reason `cliOnlyInstallCommand`). Use `kward init` from the shell.
 - `shell`: explicitly unsupported (`supported: false`, reason `interactiveTuiOnly`) because `/shell` is the local embedded TUI shell.
@@ -276,6 +278,66 @@ Moves the active branch to the selected tree entry. If the entry is a user messa
 
 Returns `{ "session": {}, "editorText": "...", "cancelled": false, "aborted": false }`. Fields with no value are omitted.
 
+## 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.
+
+### `pluginChats/open`
+
+Params:
+
+- `typeId`: an opted-in plugin chat type, such as `kward.maria`.
+
+Opens the plugin-owned chat in this RPC process and returns its metadata plus normalized transcript.
+
+### `pluginChats/transcript`
+
+Params:
+
+- `chatId`;
+- `limit`: optional bounded page size for plugin drivers that support transcript paging;
+- `before`: optional opaque cursor returned by a preceding page.
+
+Returns chat metadata and its normalized transcript. Paging-capable plugin chats return the newest page first plus `hasMore` and, when more history is available, `nextBefore`. Clients send that cursor as `before` to load the preceding page. Plugins that do not opt in retain the original complete-transcript behavior.
+
+### `pluginChats/subscribe` and `pluginChats/unsubscribe`
+
+Params:
+
+- `chatId`.
+
+Subscriptions are opt-in. `pluginChats/subscribe` enables live `pluginChat/event` notifications for that chat on the current RPC connection. `pluginChats/unsubscribe` disables them without affecting the chat or archive.
+
+### `pluginChats/turns/start`
+
+Params:
+
+- `chatId`;
+- `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.
+
+### `pluginChats/turns/cancel`, `pluginChats/turns/status`, `pluginChats/turns/events`, `pluginChats/turns/list`, `pluginChats/turns/listActive`
+
+These methods mirror the corresponding `turns/*` lifecycle methods, using `chatId` where a list filter is needed. Event replay is bounded in memory and subscriptions are required for live notifications.
+
+## Plugin chat notifications
+
+Subscribed clients receive `pluginChat/event` notifications:
+
+```json
+{
+  "chatId": "kward.maria",
+  "turnId": "...",
+  "sequence": 1,
+  "type": "assistantDelta",
+  "payload": { "delta": "text" }
+}
+```
+
+Known event types are `turnQueued`, `turnStarted`, `reasoningDelta`, `reasoningBoundary`, `assistantDelta`, `assistantMessage`, `toolCall`, `toolResult`, `answer`, `turnCancelRequested`, and `turnFinished`.
+
 ## Turn methods
 
 Turns are asynchronous. A session queues turns sequentially; only one turn runs per session at a time.
@@ -684,6 +746,16 @@ Params:
 
 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`.
 
+### `skills/captureSessions`, `skills/captureDraft`, and `skills/saveCapturedDraft`
+
+Use this two-step workflow to capture a personal skill from a saved session:
+
+1. Call `skills/captureSessions` to list available persisted session sources.
+2. Call `skills/captureDraft` with `sessionPath`. Kward sends the selected active branch, including available raw tool output, to the active model provider and returns an editable `SKILL.md` draft. It rejects a source that exceeds the active model context rather than truncating it.
+3. Review and edit `content`, then call `skills/saveCapturedDraft`. Set `overwrite: true` only after explicitly confirming replacement of an existing personal skill.
+
+Captured skills are saved under the Kward config directory, are not activated automatically, and no file is written until the final save call succeeds.
+
 ### `resources/startup`
 
 Params:

data/doc/sandboxing.md

@@ -0,0 +1,120 @@
+# Command sandboxing
+
+Kward can optionally apply an operating-system sandbox to model-requested
+`run_shell_command` calls. The sandbox is a technical boundary for the command
+and every process it starts; it is separate from Kward's [permission
+policy](permissions.md), which decides whether Kward should start a tool at all.
+
+Sandboxing is **off by default**. When you request a non-off mode and Kward
+cannot enforce it on the current platform, the command is denied rather than
+run without the requested boundary.
+
+## Configure a command sandbox
+
+Add a `sandbox` section to your user config, normally `~/.kward/config.json`:
+
+```json
+{
+  "sandbox": {
+    "mode": "workspace_write",
+    "network": "deny",
+    "writable_roots": [],
+    "protect_git_metadata": true
+  }
+}
+```
+
+Available modes are:
+
+| Mode | Command filesystem writes |
+| --- | --- |
+| `off` | Existing unrestricted command behavior. |
+| `read_only` | Workspace writes are denied. Kward gives the command a private temporary directory for command-local scratch files. |
+| `workspace_write` | Writes are allowed in the active workspace and the private command temporary directory. |
+
+`writable_roots` lets you grant additional, existing host paths to commands in
+`workspace_write` mode—for example, a known local build cache. Configure these
+paths only in your user config. Do not add a path merely because a repository
+instruction or model response asks for it. `protect_git_metadata` defaults to
+`true`; this prevents sandboxed commands from changing `.git`, including
+staging and committing changes.
+
+`network` controls child-process network access:
+
+| Value | Child-process network access |
+| --- | --- |
+| `deny` | Denied by the operating-system backend. This is the default. |
+| `allow` | Allowed with the same network reachability as your user account. |
+
+## Interactive controls
+
+Use `/sandbox` in the terminal UI to inspect or update the global policy:
+
+```text
+/sandbox status
+/sandbox read_only
+/sandbox workspace_write
+/sandbox off
+/sandbox network deny
+/sandbox network allow
+```
+
+Changes apply to newly created sessions and tabs. Existing turns keep the
+workspace and command runner they started with, so start a new session or tab
+after changing the mode.
+
+## Platform support
+
+| Platform | Backend | Status |
+| --- | --- | --- |
+| macOS | Seatbelt through `/usr/bin/sandbox-exec` | Supported for command workers. Kward checks availability at runtime. |
+| Linux | Bubblewrap | Supported when `bwrap` can create the required namespaces. |
+| Windows | None | Unsupported. A requested non-off policy fails closed. |
+
+On Debian or Ubuntu, install Bubblewrap with `sudo apt install bubblewrap`; on
+Fedora, use `sudo dnf install bubblewrap`. A present `bwrap` executable can
+still be prevented from creating namespaces by host policy. In that case,
+Kward fails the command closed instead of running it unrestricted.
+
+The macOS `sandbox-exec` utility is deprecated by Apple. Kward therefore treats
+it as a capability-detected backend and verifies enforcement with platform
+integration tests. It is not a promise that future macOS releases will retain
+this interface.
+
+## Boundaries and limits
+
+The current implementation protects **model-requested command workers only**.
+It does not sandbox:
+
+- the Kward Ruby host process;
+- model-provider, search-provider, or RPC traffic;
+- trusted Ruby plugins;
+- MCP servers, lifecycle hooks, `/shell`, `!command`, or `/pty`.
+
+Sandboxed command workers receive a minimal environment: Kward preserves only
+basic terminal, locale, and path variables, then supplies a private `HOME` and
+temporary directory. Credentials and runtime-injection variables are not
+inherited. On macOS, Seatbelt also denies reads from common credential locations
+under the host home directory, including `.kward`, `.ssh`, `.aws`, `.gnupg`, and
+selected cloud/CLI configuration directories.
+
+This is defense in depth, not complete secret-file read isolation: commands
+still receive system and development-tool reads needed for normal local work.
+On Linux, Bubblewrap provides a read-only view of the host filesystem outside
+its explicitly writable paths; it does not hide every file your account can
+read. For sensitive repositories, use a disposable checkout, VM, or container
+in addition to Kward's command sandbox.
+
+The RPC `initialize.capabilities.security.sandbox` payload reports the active
+mode, backend, and whether filesystem and child-network enforcement are active.
+It also reports unsupported features, including session pinning and one-time
+sandbox elevation; those are not available yet.
+
+## Related guides
+
+- [Security and trust](security.md) explains Kward's broader trust boundaries.
+- [Permissions](permissions.md) controls whether Kward starts a model-requested
+  tool; it does not constrain a command after it starts.
+- [Configuration](configuration.md#Command_sandboxing) covers the full config
+  section, while [Workspace tools](workspace-tools.md) explains the separate
+  file-tool guardrails.

data/doc/security.md

@@ -6,8 +6,8 @@ This guide explains the trust boundaries and gives you a safe way to start work
 
 ## The short version
 
-- Kward and anything it launches run with your operating-system permissions.
-- File tools stay inside the active workspace by default, but shell commands are not sandboxed.
+- Kward and its trusted host-process extensions run with your operating-system permissions.
+- File tools stay inside the active workspace by default. Model-requested shell commands can also use an opt-in OS-enforced command sandbox.
 - Existing files must be read before Kward's file tools can edit or overwrite them.
 - Plugins, MCP servers, command hooks, and HTTP hooks should be configured only from sources and endpoints you trust.
 - Project skills and workspace hooks are disabled until you opt in or trust them.
@@ -16,6 +16,12 @@ This guide explains the trust boundaries and gives you a safe way to start work
 
 If a task involves secrets, production credentials, customer data, or an untrusted repository, narrow the workspace and tools before asking Kward to act.
 
+## Local model endpoints and replacement prompts
+
+The Local provider defaults to loopback endpoints. If you set `local_base_url` to another host, Kward can send prompts, selected workspace content, attachments, and tool results to that host. Treat a non-loopback endpoint as a model provider: use TLS and authentication where appropriate, and do not assume a private-network address is harmless.
+
+A `system_prompt.file` replacement is model-visible and may be retained in session prompt snapshots. Do not put tokens, credentials, customer data, or other secrets in that file. Replacement mode intentionally removes Kward's normal prompt layers, including workspace guidance and skill descriptions; verify it with `kward sysprompt` before using a permissive local model.
+
 ## A safe first run in an unfamiliar repository
 
 Start with project-provided extensions disabled, which is the default:
@@ -42,7 +48,7 @@ Before enabling or running anything:
 6. Do not add repository-provided Ruby files to `~/.kward/plugins` unless you are willing to run them as your user.
 7. Ask Kward to explain proposed edits and commands before applying them when the impact is unclear.
 
-For especially sensitive work, use a disposable checkout, container, virtual machine, or restricted operating-system account. Kward's own guardrails do not replace operating-system isolation.
+For especially sensitive work, use a disposable checkout, container, virtual machine, or restricted operating-system account. Enable [command sandboxing](sandboxing.md) for model-requested shell commands, but remember that its first release does not sandbox the Kward host process, plugins, MCP servers, hooks, or interactive shell features.
 
 ## Workspace access is a guardrail, not a sandbox
 
@@ -50,8 +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:
 
-- `run_shell_command`, `!command`, `/shell`, and `/pty` run with your user permissions.
-- A shell command can access files, environment variables, processes, and networks available to your account.
+- With `sandbox.mode: off` (the default), `run_shell_command`, `!command`, `/shell`, and `/pty` run with your user permissions.
+- A non-off [command sandbox](sandboxing.md) restricts only model-requested `run_shell_command` workers and their descendants. It does not cover `!command`, `/shell`, or `/pty`.
 - Plugins, command hooks, and MCP servers are local processes with the same general operating-system access.
 - Read-before-edit applies to Kward's file tools, not to arbitrary shell commands or extension code.
 
@@ -69,6 +75,10 @@ Pan mode does not provide a dedicated hook-approval UI. Use `deny` or `warn` for
 
 See [Lifecycle hooks](lifecycle-hooks.md) for policy examples and [RPC protocol](rpc.md#Tool_approval_bridge) for the approval contract.
 
+## 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.
+
 ## Know what you are trusting
 
 ### Workspace instructions

data/doc/skills.md

@@ -42,6 +42,16 @@ The `name` and `description` fields are required. The description matters: Kward
 
 Skill names should be lowercase letters, numbers, and hyphens, such as `testing`, `code-review`, or `release-checklist`.
 
+## Capture a skill from a session
+
+Use `/skill capture` after a useful session. Choose any saved session; Kward uses its active branch and asks your active model to draft a reusable `SKILL.md`. Review and edit the draft in the terminal editor, then save it explicitly. Captured skills always go to your personal Kward skill directory and are not activated automatically.
+
+The draft request includes the complete persisted branch, including available raw tool output and saved session context. Treat it like any other model request: do not capture a session whose contents you are not willing to send to the active provider. Kward rejects a source that does not fit the active model context instead of silently truncating it.
+
+If the reviewed name already exists, Kward requires an explicit overwrite confirmation. Activate a saved draft later with `/skill <name>`.
+
+Pan provides the same saved-session picker and editable review flow. RPC clients use `skills/captureSessions`, `skills/captureDraft`, and `skills/saveCapturedDraft`; see the [RPC protocol](rpc.md).
+
 ## Skill locations
 
 User-level skills are available in every project:

data/doc/tabs.md

@@ -2,7 +2,7 @@
 
 Use tabs when you want more than one Kward conversation open in the same interactive terminal session.
 
-Each tab has its own session-backed conversation, transcript, composer state, and running agent turn. That makes tabs useful for splitting work without losing your place: one tab can investigate a bug, another can draft docs, and a third can wait on a long-running answer.
+Normal tabs have their own session-backed conversation, transcript, composer state, and running agent turn. Plugins can also provide their own persistent tab types while Kward continues to supply the same composer and tab behavior. This makes tabs useful for splitting work without losing your place: one tab can investigate a bug, another can draft docs, and a third can wait on a long-running answer.
 
 ## Quick start
 
@@ -56,6 +56,7 @@ Tabs keep the conversations separate, so context from one tab does not automatic
 | Command | Action |
 | ------- | ------ |
 | `/tab new` | Open a new tab with a fresh conversation |
+| `/tab open <plugin-tab>` | Open a plugin-provided tab, such as a persistent companion chat. |
 | `/tab 1` through `/tab 9` | Switch to a numbered tab |
 | `/tab close` | Close the current tab |
 | `/tab name <label>` | Rename the current tab |
@@ -110,9 +111,9 @@ Slash commands such as `/tab` still work while a tab is busy, so you can switch
 
 ## Persistence
 
-Tabs are backed by normal Kward sessions. Kward stores the open tab list, labels, and active tab per workspace, then restores them the next time you start interactive Kward in that workspace.
+Normal tabs are backed by Kward sessions. Plugins may also provide their own tab types; those tabs own their transcript and persistence independently of Kward sessions.
 
-The tab layout is stored in Kward's config directory under `tabs/`. Session transcripts stay in the normal sessions directory. See [Sessions](session-management.md) for session naming, resuming, forking, exporting, and cleanup.
+Kward stores the open tab list, labels, and active tab per workspace, then restores them the next time you start interactive Kward in that workspace. The tab layout is stored in Kward's config directory under `tabs/`. Session transcripts stay in the normal sessions directory. See [Sessions](session-management.md) for session naming, resuming, forking, exporting, and cleanup.
 
 ## Notes and limitations
 

data/doc/web-search.md

@@ -85,7 +85,9 @@ Arguments:
 - `max_bytes`: default 16384, capped at 131072.
 - `extract`: optional `auto`, `text`, or `markdown`.
 
-In `auto` mode (default), Kward detects HTML content and extracts readable text by stripping scripts, styles, navigation, and forms, preserving headings, paragraphs, lists, code blocks, and blockquotes. Non-HTML content is returned as cleaned text. Use `markdown` to format extracted headings and code blocks as Markdown, or `text` for plain text without formatting.
+In `auto` mode (default), Kward detects HTML content and extracts readable text while stripping scripts, styles, navigation prose, and forms. It preserves headings, paragraphs, ordered and unordered lists, code blocks, blockquotes, simple tables, and inline link destinations. A bounded `Links` section lists discovered main-content and navigation destinations so an agent can continue through a site without raw HTML. Relative links are resolved against the final fetched URL. Non-HTML content is returned as cleaned text. Use `markdown` to retain Markdown structure, or `text` for plain text with link destinations in parentheses.
+
+Kward downloads and parses up to 2 MB of a page before applying `max_bytes` to the extracted result. This lets pages with large scripts or metadata before their main content remain readable while keeping model-facing output bounded. Responses above the download limit are rejected rather than parsed as incomplete HTML.
 
 Fetches follow up to 5 redirects and use a 10-second HTTP timeout.
 
@@ -99,4 +101,4 @@ Arguments:
 - `max_bytes`: default 16384, capped at 131072.
 - `accept`: optional HTTP `Accept` header.
 
-Fetches follow up to 5 redirects and use a 10-second HTTP timeout.
+Fetches follow up to 5 redirects, enforce the requested byte limit while reading the response, and use a 10-second HTTP timeout.

data/doc/workspace-tools.md

@@ -12,14 +12,14 @@ Kward normally chooses these tools itself. You do not need to know their exact n
 
 ## Guardrails
 
-Workspace tools use the active workspace as their boundary. File paths are workspace-relative by default, and file tools are guarded so Kward does not edit arbitrary unread files. Guardrails can be disabled with the `tools.workspace_guardrails` setting — see [Configuration](configuration.md). When disabled, file tools can access paths outside the workspace, but shell commands are unaffected since they already run as your OS user.
+Workspace tools use the active workspace as their boundary. File paths are workspace-relative by default, and file tools are guarded so Kward does not edit arbitrary unread files. Guardrails can be disabled with the `tools.workspace_guardrails` setting — see [Configuration](configuration.md). When disabled, file tools can access paths outside the workspace. These guardrails do not affect shell commands; model-requested commands can instead use the separate, opt-in [command sandbox](sandboxing.md).
 
 Important behavior:
 
 - Existing files must be read in the current conversation before `write_file` or `edit_file` can change them.
 - Reads are bounded to avoid pulling very large files into context by accident. Files larger than 256 KB cannot be read or edited. Read output is capped at 50 KB or 2,000 lines, whichever comes first.
 - Edits use exact text replacement, so accidental partial or fuzzy changes fail instead of guessing.
-- Shell commands run as your operating-system user from the workspace. They are powerful and should be treated like commands you run yourself. Command output is capped at 128 KB.
+- 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.
 
 ## Reading the workspace
 
@@ -124,7 +124,7 @@ Arguments:
 - `command`: command to run.
 - `timeout_seconds`: optional timeout, default 30 seconds.
 
-Kward uses shell commands for tests, linters, build checks, and simple repository inspection. Command output is bounded at 128 KB and may be compacted before it is sent back into model context, while the original output remains available in the session record.
+Kward uses shell commands for tests, linters, build checks, and simple repository inspection. When configured, the [command sandbox](sandboxing.md) applies to this tool and its descendants. Command output is bounded at 128 KB and may be compacted before it is sent back into model context, while the original output remains available in the session record.
 
 The output format is `Exit status: N` followed by `STDOUT:` and `STDERR:` sections. On timeout, Kward sends SIGTERM then SIGKILL after 0.2 seconds and returns a timeout error. Commands support cooperative cancellation when the session is cancelled.
 

data/kward.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.description = "Kward is a Ruby CLI coding agent with local workspace tools, configurable prompts, web search, sessions, and an experimental JSON-RPC backend."
   spec.homepage = "https://github.com/kaiwood/kward"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.2"
+  spec.required_ruby_version = ">= 3.4"
 
   spec.metadata["rubygems_mfa_required"] = "true"
   spec.metadata["source_code_uri"] = "https://github.com/kaiwood/kward"