kward 0.78.0 → 0.79.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e77436e5f94e314fcab35e347c16994eb8f92f990ad4c3ebdc6ab76a393cb1b4
-  data.tar.gz: 50b73b48c76c737d5b7d2534380547d94e357cac6dec4528a80cfe36ea8f6bdf
+  metadata.gz: 79174a2cb7441a44857a53568078c50b2c7735d7a8f7507ce6e8d1199f8b37fa
+  data.tar.gz: c83fda7c64aea1ad5f8af38c5ee0bb1d0c56a3c05efa3457c02fcd5b3049cb99
 SHA512:
-  metadata.gz: bc17d7227fa1910ee107b840ec138ee19c8ed905d137d7aeed3fc552e2ec6d3aca1fb3d8df4febce7c7e84380a7e4f4378c3177415b3ab7a59fb22d344b92d2c
-  data.tar.gz: 56521cdb264f5745f2023a010892b99ec91693f4444c17c0f1aa7b9375e9d0727ba7c9ce280d4e0af9141ae5466073393fbf9d112d53bf7ea12872aa68c7f617
+  metadata.gz: 9088afe9fb4976a8a40ec08a0297ee99d075f9df756465f68e04482c55f5fbb1d5b0b8d5e20b880d258253d8e015ce91b745a1db57c3ce03374b912d4fc109fe
+  data.tar.gz: 7452c7d1674338e52b3216f648b798f9181cf421db840bc54a74270acebd40c1aa67aa1c2dbbfaea322908cd50344e34500a79cb68033bdfc1fa62642cefbf20

data/.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ['3.2', 'ruby']
+        ruby-version: ['3.4', 'ruby']
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -27,11 +27,16 @@ jobs:
           ruby-version: ${{ matrix.ruby-version }}
           bundler-cache: true
 
+      - name: Install sandbox test dependency
+        run: sudo apt-get update && sudo apt-get install --yes bubblewrap
+
       - name: Check syntax
         run: find lib test -name '*.rb' -print0 | xargs -0 ruby -c
 
       - name: Check runtime warnings
-        run: ruby -w -Ilib -e 'require "kward"'
+        run: bundle exec ruby -w -Ilib -e 'require "kward"'
 
       - name: Run tests
+        env:
+          KWARD_RUN_BUBBLEWRAP_TESTS: "1"
         run: bundle exec rake test

data/.github/workflows/pages.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.3'
+          ruby-version: '3.4'
           bundler-cache: true
 
       - name: Build documentation

data/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to Kward will be documented in this file.
 
 ## [Unreleased]
 
+## [0.79.0] - 2026-07-19
+
+### Added
+
+- Added a Local OpenAI-compatible model provider for Ollama, LM Studio, and llama.cpp, including model discovery, streamed tool calls, configurable context windows, CLI/RPC model selection, and a local-model setup guide.
+- Added replacement system-prompt files and an option to omit global principles for smaller-model prompt budgets.
+- Added skill capture from saved session branches. Review model-generated personal `SKILL.md` drafts in the CLI or Pan, or use the equivalent RPC workflow before explicitly saving them.
+- Added opt-in OS-enforced sandboxing for model-requested shell commands. macOS uses Seatbelt and Linux uses Bubblewrap when available; requested sandboxing fails closed when no supported backend can enforce it. The interactive `/sandbox` command reports and updates the global policy.
+
+### Changed
+
+- Clarified command-sandbox configuration, platform setup, and limits across the security, permissions, workspace-tools, RPC, and configuration guides.
+- Sandboxed command workers now receive a sanitized environment with a private home and temporary directory; the macOS backend also blocks reads from common credential directories.
+- Improved built-in tool guidance so agents use only tools advertised for the current turn and select code search, compacted-output retrieval, and structured clarification when appropriate.
+- Raised the minimum supported Ruby version from 3.2 to 3.4.
+
+### Fixed
+
+- Reject duplicate discovered tool names instead of silently replacing one MCP tool with another.
+- Fixed an RPC race where follow-up input could queue instead of steering a turn immediately after it began.
+- Prevented the RPC server from loading trusted Ruby plugins separately for plugin chats and workspace sessions, eliminating duplicate constant-definition warnings during startup.
+- Prevented `/reload` and RPC runtime reloads from emitting duplicate constant-definition warnings for plugin-defined constants.
+- Wrapped long side-by-side diff cells when editor soft wrap is enabled instead of clipping their contents.
+
 ## [0.78.0] - 2026-07-15
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kward (0.78.0)
+    kward (0.79.0)
       base64
       nokogiri
       tiktoken_ruby
@@ -146,7 +146,7 @@ CHECKSUMS
   html-proofer (5.2.1) sha256=fdd958a7cbf9c3255fb96fe7cfc4e611f64e2706e469488a3326309ad007d2fd
   io-event (1.16.2) sha256=9f9cb0a96ea5c3850a672606c65f27bc96d7621399ef6196acbfe2be0cd1279c
   json (2.19.9) sha256=9b9025b7cdddafa38d316eca0b2358488e42d417045c1b90d216a9fefe46b79a
-  kward (0.78.0)
+  kward (0.79.0)
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   metrics (0.15.0) sha256=61ded5bac95118e995b1bc9ed4a5f19bc9814928a312a85b200abbdac9039072
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1

data/README.md

@@ -1,8 +1,8 @@
 # Kward
 
-Kward is an extendable Ruby CLI coding agent. It can chat with you about a project, inspect and edit files, run confirmed shell commands, search the web, look up public source code, save local sessions, and load trusted Ruby plugins for custom workflows.
+Kward is an extendable Ruby CLI coding agent. It can chat with you about a project, inspect and edit files, run local shell commands, search the web, look up public source code, save local sessions, and load trusted Ruby plugins for custom workflows.
 
-It currently supports the OpenAI/ChatGPT Codex backend, Anthropic Claude Pro/Max subscription, OpenRouter, and experimental Copilot provider support.
+It supports the OpenAI/ChatGPT Codex backend, Anthropic Claude Pro/Max subscription, OpenRouter, experimental Copilot provider support, and OpenAI-compatible local servers such as Ollama, LM Studio, and llama.cpp.
 
 ## Why use Kward?
 
@@ -77,6 +77,7 @@ Start here:
 - [Authentication](doc/authentication.md): OpenAI OAuth, Anthropic OAuth, OpenRouter API keys, and Copilot/GitHub setup.
 - [Security and trust](doc/security.md): local permissions, external data flow, trusted extensions, and safe work in unfamiliar repositories.
 - [Permissions](doc/permissions.md): opt-in tool approval, write scopes, policy rules, and current limits.
+- [Command sandboxing](doc/sandboxing.md): opt-in OS-enforced boundaries for model-requested shell commands.
 - [Troubleshooting](doc/troubleshooting.md): environment-specific install and runtime issues.
 
 Feature guides:
@@ -93,6 +94,7 @@ Feature guides:
 - [Skills](doc/skills.md): add reusable instructions that load only for matching tasks.
 - [MCP servers](doc/mcp.md): connect trusted local Model Context Protocol tool servers.
 - [Pan mode](doc/pan.md): use the mobile-friendly browser interface on a trusted local network.
+- [Local models](doc/local-models.md): connect Ollama, LM Studio, or llama.cpp and use a minimal replacement prompt.
 
 Advanced:
 

data/doc/agent-tools.md

@@ -38,7 +38,7 @@ This lets the assistant reason from focused evidence while preserving access to
 
 ## How tools are exposed
 
-`Kward::ToolRegistry` builds the available tool objects and the schemas advertised to the model. Some tools are always available in normal CLI/RPC sessions, while others depend on configuration or frontend capability:
+`Kward::ToolRegistry` builds the available tool objects and the schemas advertised to the model. Kward instructs models to call only tools advertised for the current turn; a restricted RPC turn therefore receives schemas only for its selected set. Some tools are always available in normal CLI/RPC sessions, while others depend on configuration or frontend capability:
 
 - web tools can be hidden with web search configuration,
 - `read_skill` is advertised only when skills are available,

data/doc/configuration.md

@@ -15,6 +15,7 @@ If `KWARD_CONFIG_PATH` is set, Kward uses that file and treats its directory as
 | Change editor, diff, overlay, or session UI behavior | `/settings` → Interface |
 | Enable memory | `/settings` → Memory |
 | Configure web search or trust project skills | `/settings` → Tools & Search |
+| Contain model-requested shell commands | `/sandbox` for mode and child-network access; edit config for additional writable roots |
 | Tune compaction | `/settings` → Context & Compaction |
 | Configure personas | `/settings` → Personalization; see [Personas](personas.md) |
 | Add MCP servers, lifecycle hooks, or environment-specific paths | Edit `config.json` directly |
@@ -161,6 +162,7 @@ Supported values are:
 - `anthropic` for Anthropic Claude Pro/Max subscription support.
 - `openrouter` for OpenRouter.
 - `copilot` for experimental Copilot provider support.
+- `local` for an OpenAI-compatible Ollama, LM Studio, or llama.cpp server. See [Local models](local-models.md).
 
 Model settings:
 
@@ -171,6 +173,7 @@ Model settings:
   "openrouter_model": "openai/gpt-5.6-sol",
   "anthropic_model": "claude-sonnet-5",
   "copilot_model": "gpt-5-mini",
+  "local_model": "qwen2.5-coder:7b",
   "reasoning_effort": "medium",
   "openai_reasoning_effort": "medium",
   "openrouter_reasoning_effort": "medium",
@@ -184,7 +187,7 @@ Model settings:
 
 Set `codex_show_raw_reasoning` to `true` to display raw Codex `reasoning_text` when the API does not provide reasoning summary text. It defaults to `false`; raw reasoning can include internal or unstable model output, so enable it only when you explicitly want to inspect that stream.
 
-`stream_idle_timeout_seconds` limits how long a streamed Codex or Anthropic response may go without receiving data. It defaults to `120`; set a positive value to override it. When the provider is silent longer than this limit, Kward closes the request and applies its normal transient-network retry behavior.
+`stream_idle_timeout_seconds` limits how long a streamed Codex, Anthropic, or Local response may go without receiving data. It defaults to `120`; set a positive value to override it. When the provider is silent longer than this limit, Kward closes the request and applies its normal transient-network retry behavior.
 
 Defaults:
 
@@ -198,6 +201,24 @@ The Anthropic model choices include `claude-fable-5`, but Fable availability dep
 
 The interactive `/model` picker reads cached OpenRouter models when available. Run `kward openrouter refresh` to fetch text-capable models available to the configured OpenRouter API key and cache them under `~/.kward/cache/openrouter_models.json`. Run `kward openrouter list` to inspect the cached model ids.
 
+### Local model server
+
+The `local` provider uses OpenAI-compatible Chat Completions and model-list endpoints. Configure a running local server with a model id and its actual context window:
+
+```json
+{
+  "provider": "local",
+  "local_backend": "ollama",
+  "local_base_url": "http://127.0.0.1:11434/v1",
+  "local_model": "qwen2.5-coder:7b",
+  "local_context_window": 32768
+}
+```
+
+`local_backend` selects a convenience default: `ollama`, `lm_studio`, or `llama_cpp`. Their default base URLs are `http://127.0.0.1:11434/v1`, `http://127.0.0.1:1234/v1`, and `http://127.0.0.1:8080/v1`, respectively. Set `local_base_url` to use a custom endpoint. `local_api_key` is optional and is sent as a bearer token only when configured.
+
+Set `local_context_window` to the context length configured for the loaded model. Kward does not infer this safely from an arbitrary local model name; without it, automatic context budgeting cannot report a reliable limit. Local providers do not expose Kward reasoning or image controls by default.
+
 ## Environment overrides
 
 Use environment variables for one-off runs or local secrets that you do not want in config.
@@ -209,6 +230,11 @@ Provider and model:
 - `OPENAI_REASONING_EFFORT`
 - `OPENROUTER_MODEL`
 - `OPENROUTER_REASONING_EFFORT`
+- `KWARD_LOCAL_BACKEND`
+- `KWARD_LOCAL_BASE_URL`
+- `KWARD_LOCAL_MODEL`
+- `KWARD_LOCAL_CONTEXT_WINDOW`
+- `KWARD_LOCAL_API_KEY`
 - `ANTHROPIC_MODEL`
 - `ANTHROPIC_REASONING_EFFORT`
 - `COPILOT_MODEL`
@@ -502,6 +528,31 @@ Do not put shared or published API keys in this file.
 
 Put global engineering principles in `PRINCIPLES.md` beside your config file, usually `~/.kward/PRINCIPLES.md`. Kward appends this file to its built-in system instructions when present. Existing config-directory `AGENTS.md` files are still read as a legacy alias when `PRINCIPLES.md` is absent.
 
+## Replacement system prompt
+
+Set `system_prompt.file` to use a file as the entire system prompt. In replacement mode Kward does not append its built-in instructions, global principles, memory context, personas, plugin context, skills, or workspace `AGENTS.md` guidance.
+
+```json
+{
+  "system_prompt": {
+    "file": "prompts/local-minimal.md",
+    "include_principles": false
+  }
+}
+```
+
+Relative paths are resolved beside `config.json`. The file is sent to the configured model and can be recorded in session prompt snapshots, so do not place secrets in it. Use `kward sysprompt` to inspect the exact active prompt.
+
+To retain Kward's normal prompt while omitting only global `PRINCIPLES.md` (and its legacy config-directory `AGENTS.md` fallback), configure:
+
+```json
+{
+  "system_prompt": {
+    "include_principles": false
+  }
+}
+```
+
 ## Workspace AGENTS.md
 
 By default, Kward does not inject the full workspace `AGENTS.md` into every request. When a workspace `AGENTS.md` exists, Kward injects a compact instruction telling the model to read it for repository-related tasks before analyzing or modifying project files.
@@ -528,7 +579,22 @@ Workspace guardrails are enabled by default. File tools such as `read_file`, `wr
 }
 ```
 
-This is not a sandbox setting. Shell commands already run as your OS user from the workspace directory and can access anything that user can access.
+This is not a sandbox setting. File guardrails constrain Kward file tools, not arbitrary shell commands. See [Command sandboxing](sandboxing.md) to apply an opt-in operating-system boundary to model-requested `run_shell_command` workers.
+
+## Command sandboxing
+
+Sandboxing is off by default. Use `/sandbox` to inspect or change the mode and child-network access. For additional writable roots or Git metadata protection, edit the `sandbox` config directly. `sandbox.mode` accepts `off`, `read_only`, or `workspace_write`; `sandbox.network` defaults to `deny`, and `sandbox.protect_git_metadata` defaults to `true`.
+
+```json
+{
+  "sandbox": {
+    "mode": "workspace_write",
+    "network": "deny"
+  }
+}
+```
+
+When Kward cannot enforce a requested non-off mode, it denies the command rather than running it unrestricted. Current support and limits are documented in [Command sandboxing](sandboxing.md).
 
 ## Permissions
 

data/doc/extensibility.md

@@ -43,6 +43,8 @@ If `KWARD_CONFIG_PATH` is set, `PRINCIPLES.md` lives beside that config file.
 
 If `PRINCIPLES.md` is absent, Kward also reads `~/.kward/AGENTS.md` (or the equivalent beside a custom config path) as a legacy alias. New setups should use `PRINCIPLES.md`. See [Configuration](configuration.md) for details.
 
+For a small local model, set `system_prompt.include_principles` to `false` to keep Kward's normal prompt without global principles. Set `system_prompt.file` only when you want the file to replace the entire assembled system prompt; replacement mode also omits personas, skills, memory, plugins, and workspace guidance. See [Local models](local-models.md) for a complete setup.
+
 ## Project instructions: `AGENTS.md`
 
 Put repository-specific rules in the workspace root:

data/doc/getting-started.md

@@ -6,7 +6,7 @@ This page gets you from install to a first useful chat.
 
 ## Requirements
 
-- Ruby 3.2 or newer.
+- Ruby 3.4 or newer.
 - Credentials for one model provider. The easiest setup is `kward login` or `/login` inside Kward.
 - Bundler only if you run Kward from a source checkout.
 

data/doc/local-models.md

@@ -0,0 +1,130 @@
+# Local models
+
+Kward can connect to a local model server that provides OpenAI-compatible Chat Completions. This is useful when you want offline development, control over model selection, or a smaller prompt for a local coding model.
+
+Kward connects to an already-running server. It does not install runtimes, download models, choose GPU settings, or load models for you.
+
+## Choose and start a runtime
+
+Use one of these local servers:
+
+| Runtime | Default Kward base URL |
+| --- | --- |
+| Ollama | `http://127.0.0.1:11434/v1` |
+| LM Studio | `http://127.0.0.1:1234/v1` |
+| llama.cpp `llama-server` | `http://127.0.0.1:8080/v1` |
+
+Start the server and load a chat model before starting Kward. Then confirm that it reports models:
+
+```bash
+curl http://127.0.0.1:11434/v1/models
+```
+
+Use the equivalent configured port for LM Studio or llama.cpp.
+
+## Configure Kward
+
+Add a Local provider configuration to `~/.kward/config.json`:
+
+```json
+{
+  "provider": "local",
+  "local_backend": "ollama",
+  "local_model": "qwen2.5-coder:7b",
+  "local_context_window": 32768
+}
+```
+
+`local_backend` supplies a default endpoint for `ollama`, `lm_studio`, or `llama_cpp`. Set `local_base_url` when the server uses another host, port, path, Docker address, reverse proxy, or TLS endpoint:
+
+```json
+{
+  "provider": "local",
+  "local_base_url": "http://127.0.0.1:1234/v1",
+  "local_model": "loaded-model-id",
+  "local_context_window": 32768
+}
+```
+
+Set `local_context_window` to the context length actually configured for the loaded model. Kward cannot reliably infer it from a local model name. The value lets Kward report meaningful context usage and make safe auto-compaction decisions.
+
+If your local proxy requires a token, set `local_api_key` or `KWARD_LOCAL_API_KEY`. Kward sends it as a bearer token only for Local requests.
+
+You can also choose **Local** from `/settings` → **Model & Reasoning** → **Provider**, then select a model with `/model`.
+
+## Use a minimal replacement prompt
+
+Smaller models often work better with a short, direct prompt. Create a file beside your Kward config, for example `~/.kward/prompts/local-minimal.md`:
+
+```markdown
+You are a coding assistant.
+Use the provided tools when needed.
+Inspect relevant files before changing them.
+Make only requested changes and report what changed.
+```
+
+Configure it as Kward's replacement system prompt:
+
+```json
+{
+  "system_prompt": {
+    "file": "prompts/local-minimal.md",
+    "include_principles": false
+  }
+}
+```
+
+This file is the entire system prompt. Kward does not add its built-in instructions, `PRINCIPLES.md`, memory context, personas, plugin context, skills, or workspace `AGENTS.md` guidance in replacement mode.
+
+If you want Kward's normal prompt but do not want global principles sent on every turn, omit the `file` and disable only principles:
+
+```json
+{
+  "system_prompt": {
+    "include_principles": false
+  }
+}
+```
+
+Check the exact result before relying on it:
+
+```bash
+kward sysprompt
+kward sysprompt --raw
+```
+
+Do not put secrets in a replacement prompt. Its contents are sent to the model and may be stored as a session prompt snapshot.
+
+## Verify tool calling
+
+A coding agent needs more than ordinary chat: the model must request tools with valid arguments and use their results. Start with a safe read-only task:
+
+```text
+Read README.md and summarize the project's test command. Do not modify files.
+```
+
+Choose a model trained for tool or function calling. If it responds with prose instead of tool calls, use a tool-capable model or make the replacement prompt's tool guidance more explicit.
+
+## Security and limits
+
+The default endpoints use loopback addresses. If you configure another host, Kward can send prompts, workspace-derived content, attachments, and tool results over that connection. Use TLS and authentication for any endpoint outside your machine or trusted private network.
+
+Local model support uses the OpenAI-compatible Chat Completions interface, including streaming text and function/tool calls. Kward does not promise reasoning controls or image support for arbitrary local models.
+
+## Troubleshooting
+
+**No models appear in `/model`**
+
+Confirm the server is running, a model is loaded, and `GET /v1/models` succeeds. You can still set `local_model` manually when discovery is unavailable.
+
+**The model stops early or Kward compacts too soon**
+
+Check `local_context_window`. It must match the server's loaded-model context setting, not just the model's advertised training context.
+
+**Tool calls are malformed or missing**
+
+Use a tool-trained model and a compatible chat template. Test with a read-only task before allowing writes or shell commands.
+
+**The server is slow**
+
+Reduce the model size, reduce context length, verify GPU acceleration in the local runtime, or raise `stream_idle_timeout_seconds` if the server has long silent intervals.

data/doc/permissions.md

@@ -2,7 +2,7 @@
 
 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.
+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
 
@@ -169,11 +169,12 @@ The policy runs before Kward dispatches a model-requested tool. It does not cons
 - 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. A future OS-enforced sandbox may provide stronger filesystem and network isolation; it is not part of the current permissions feature.
+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/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

@@ -62,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.
@@ -745,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.