kward 0.77.0 → 0.78.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a18a2a0c800780596999ee897ed61afcef22c964012f2b2ed3f51a3a66239c5
-  data.tar.gz: 83badb23b87cae5e3198e00c65f0c53acbe2e0561f00164c4e5b40aacb3d10d4
+  metadata.gz: e77436e5f94e314fcab35e347c16994eb8f92f990ad4c3ebdc6ab76a393cb1b4
+  data.tar.gz: 50b73b48c76c737d5b7d2534380547d94e357cac6dec4528a80cfe36ea8f6bdf
 SHA512:
-  metadata.gz: 5c4bd15eb61a2b62b5165b46d393fa60608dc702b773cbb0596bdd64deed1799332f22a5b271c146142f8f1f2769111e3e0075db34626818a71c4e502a14b49d
-  data.tar.gz: 9953137b41415eff742904f3a4f4d63a610da01351000d5b08d4191ad180bfbdff5c001315513bbf4fabd1918843a6c214712f9af737c0025c5494e6c84494f8
+  metadata.gz: bc17d7227fa1910ee107b840ec138ee19c8ed905d137d7aeed3fc552e2ec6d3aca1fb3d8df4febce7c7e84380a7e4f4378c3177415b3ab7a59fb22d344b92d2c
+  data.tar.gz: 56521cdb264f5745f2023a010892b99ec91693f4444c17c0f1aa7b9375e9d0727ba7c9ce280d4e0af9141ae5466073393fbf9d112d53bf7ea12872aa68c7f617

data/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to Kward will be documented in this file.
 
 ## [Unreleased]
 
+## [0.78.0] - 2026-07-15
+
+### Added
+
+- Added opt-in transcript-observer delivery for plugin-owned tabs, including RPC plugin chats, so local integrations such as text-to-speech can receive permitted streamed replies.
+- Added opt-in RPC support for plugin-owned chats, including explicit subscriptions, transcript snapshots, attachment-capable turns, event replay, and cancellation. Plugins remain disabled from this surface unless their tab type explicitly opts in.
+- Added plugin-owned tab types, opened with `/tab open <plugin-tab>`, with typed tab persistence and the normal interactive composer, transcript, streaming, and image-input behavior. Plugin tabs are CLI-only in this release and own their own storage rather than Kward sessions.
+- Added an opt-in permission policy for model-requested tools, with allow/ask/deny rules, read-only and workspace-write modes, write scopes, and interactive approval overlays. Permissions remain disabled by default and are not an OS sandbox.
+- Added a custom-response path to permission approval overlays: choosing `Type something` denies the requested tool call and returns the entered guidance to the agent.
+
+### Changed
+
+- Plugin-chat transcript RPC supports optional bounded, cursor-based pages for plugin drivers that opt in, avoiding full-history payloads for long-lived chats.
+- Code search now synchronizes mutable repository refs before every read and search, reports the resolved commit, and accepts GitHub blob URLs as file inputs.
+- Web and code research tools now cooperate with turn cancellation between requests, provider attempts, redirects, and repository scan files.
+- Kward-owned HTTP requests now identify themselves with `User-Agent: Kward/<version>`.
+
+### Fixed
+
+- Fixed `fetch_content` site navigation by preferring semantic main content over nested article cards, preserving inline and standalone link destinations, listing bounded discovered navigation links, and extracting ordered lists and simple tables.
+- Prevented duplicate session-backed tabs from restoring as mirrored conversations after restart.
+- Fixed `fetch_content` on documentation pages with large scripts or metadata before the main content by separating bounded page downloads from extracted output limits; plain-text extraction now parses HTML instead of returning cleaned markup.
+- Fixed raw fetches so their response limit is enforced while reading the network body.
+- Fixed stale code-search reads and searches by treating cached repositories as reusable local storage rather than authoritative snapshots.
+- Restored GPT-5.6 Luna requests through Codex with a scoped Responses Lite compatibility workaround; normal Codex requests retain Kward's own identity.
+
 ## [0.77.0] - 2026-07-11
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kward (0.77.0)
+    kward (0.78.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.77.0)
+  kward (0.78.0)
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   metrics (0.15.0) sha256=61ded5bac95118e995b1bc9ed4a5f19bc9814928a312a85b200abbdac9039072
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1

data/README.md

@@ -76,6 +76,7 @@ Start here:
 - [Configuration](doc/configuration.md): config files, providers, models, web search, logging, and color output.
 - [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.
 - [Troubleshooting](doc/troubleshooting.md): environment-specific install and runtime issues.
 
 Feature guides:

data/doc/code-search.md

@@ -85,9 +85,9 @@ The tool uses an `action` parameter:
 | --- | --- |
 | `package_search` | find package metadata and likely source repositories. |
 | `github_search` | search public GitHub repositories. |
-| `repo_clone` | clone a GitHub repository into cache. |
-| `repo_search` | search files in a cached repository. |
-| `repo_read` | read a bounded line range from a cached file. |
+| `repo_clone` | prewarm the local Git repository store. |
+| `repo_search` | synchronize and search files in a repository. |
+| `repo_read` | synchronize and read a bounded line range from a file. |
 | `list_cache` | show cached repositories. |
 | `refresh_cache` | fetch updates for a cached repository. |
 | `clear_cache` | remove a cached repository. |
@@ -99,13 +99,16 @@ The tool uses an `action` parameter:
 | `package_search` | `ecosystem`, `package` | — |
 | `github_search` | `query` | `ecosystem`, `max_results` |
 | `repo_clone` | `repo` | — |
-| `repo_search` | `repo`, `query` | `max_results`, `context_lines` |
-| `repo_read` | `repo`, `path` | `start_line`, `line_count` |
+| `repo_search` | `repo`, `query` | `ref`, `max_results`, `context_lines` |
+| `repo_read` | `repo` | `path`, `ref`, `start_line`, `line_count` |
 | `list_cache` | — | — |
 | `refresh_cache` | `repo` | — |
 | `clear_cache` | `repo` | — |
 
-- `repo` is a GitHub URL or `owner/name`.
+- `repo` is a GitHub URL or `owner/name`. A GitHub `blob` URL can supply the file path and ref for `repo_read`.
+- `ref` selects a branch, tag, or commit. Mutable refs are fetched before every read or search; without `ref`, Kward synchronizes the remote default branch.
+- Successful reads and searches report the exact commit revision used. The local Git store reduces repeated downloads but is never silently treated as current source.
+- If synchronization fails, Kward returns an error instead of silently answering from stale files.
 - `query` is a plain-text search string (not regex). Matching is case-sensitive substring.
 - `start_line` is 1-indexed.
 - `context_lines` controls how many lines before and after a match are included in search snippets.

data/doc/configuration.md

@@ -184,6 +184,8 @@ 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.
+
 Defaults:
 
 - OpenAI/Codex: `gpt-5.6-sol`
@@ -528,6 +530,43 @@ 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.
 
+## Permissions
+
+Permissions are off by default. When enabled, Kward evaluates model-requested tools before execution. This is a permission policy, not an operating-system sandbox: permitted shell commands still run with your user account's access.
+
+```json
+{
+  "permissions": {
+    "enabled": true,
+    "mode": "ask"
+  }
+}
+```
+
+Available modes are:
+
+| Mode | Behavior |
+| --- | --- |
+| `ask` | Read-only tools run normally; file changes, shell commands, web tools, and MCP tools need approval. |
+| `workspace-write` | File changes within `write_scopes` run without approval; shell and network tools still need approval. |
+| `read-only` | Denies file changes, shell commands, web tools, and MCP tools. |
+| `deny-by-default` | Denies risky tools unless an `allow` rule matches. |
+
+`allow`, `ask`, and `deny` rules are arrays of objects matching `tool`, `path`, `host`, `command`, or `source`. Deny rules always take precedence, then ask, then allow. Use `write_scopes` to restrict writes in `workspace-write` mode:
+
+```json
+{
+  "permissions": {
+    "enabled": true,
+    "mode": "workspace-write",
+    "write_scopes": ["lib/**", "test/**"],
+    "deny": [{ "tool": "run_shell_command", "command": "git push*" }]
+  }
+}
+```
+
+The interactive CLI presents an approval overlay for an `ask` decision. RPC clients can use their existing `approvalMode: "ask"` bridge. Frontends without an approval bridge, including Pan, fail closed for policy approvals.
+
 ## Logging and stats
 
 Local telemetry logs are off by default. Enable logging with the master flag and each category you want:

data/doc/permissions.md

@@ -0,0 +1,179 @@
+# 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.
+
+## 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. A future OS-enforced sandbox may provide stronger filesystem and network isolation; it is not part of the current permissions feature.
+
+## Related guides
+
+- [Security and trust](security.md): trust boundaries, extensions, and safe work in unfamiliar repositories.
+- [Configuration](configuration.md#Permissions): the complete configuration reference.
+- [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/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.
@@ -276,6 +277,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.

data/doc/security.md

@@ -69,6 +69,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/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/lib/kward/auth/anthropic_oauth.rb

@@ -202,8 +202,8 @@ module Kward
       parse_successful_json(response, "Anthropic OAuth token exchange")
     end
 
-    def post_json(uri, params)
-      super(uri, params, headers: { "Accept" => "application/json" })
+    def post_json(uri, params = nil, **keyword_params)
+      super(uri, params, headers: { "Accept" => "application/json" }, **keyword_params)
     end
   end
 end

data/lib/kward/auth/github_oauth.rb

@@ -4,6 +4,7 @@ require "time"
 require "uri"
 require_relative "file"
 require_relative "../config_files"
+require_relative "../http"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -15,7 +16,6 @@ module Kward
     DEFAULT_SCOPE = "read:user"
     DEFAULT_CLIENT_ID = "Iv1.b507a08c87ecfe98"
     COPILOT_HEADERS = {
-      "User-Agent" => "GitHubCopilotChat/0.35.0",
       "Editor-Version" => "vscode/1.107.0",
       "Editor-Plugin-Version" => "copilot-chat/0.35.0",
       "Copilot-Integration-Id" => "vscode-chat"
@@ -150,7 +150,7 @@ module Kward
     end
 
     def post_form(uri, params)
-      request = Net::HTTP::Post.new(uri)
+      request = Http.apply_user_agent(Net::HTTP::Post.new(uri))
       request["Content-Type"] = "application/x-www-form-urlencoded"
       request["Accept"] = "application/json"
       request.body = URI.encode_www_form(params)
@@ -160,7 +160,7 @@ module Kward
     end
 
     def get_json(uri, headers = {})
-      request = Net::HTTP::Get.new(uri)
+      request = Http.apply_user_agent(Net::HTTP::Get.new(uri))
       request["Accept"] = "application/json"
       COPILOT_HEADERS.merge(headers).each { |key, value| request[key] = value }
 

data/lib/kward/auth/oauth_helpers.rb

@@ -6,6 +6,7 @@ require "securerandom"
 require "socket"
 require "time"
 require "uri"
+require_relative "../http"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -58,8 +59,9 @@ module Kward
       socket&.close
     end
 
-    def post_json(uri, params, headers: {})
-      request = Net::HTTP::Post.new(uri)
+    def post_json(uri, params = nil, headers: {}, **keyword_params)
+      params = (params || {}).merge(keyword_params)
+      request = Http.apply_user_agent(Net::HTTP::Post.new(uri))
       request["Content-Type"] = "application/json"
       headers.each { |key, value| request[key] = value }
       request.body = JSON.dump(params)

data/lib/kward/auth/openai_oauth.rb

@@ -5,6 +5,7 @@ require "time"
 require "uri"
 require_relative "file"
 require_relative "oauth_helpers"
+require_relative "../http"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -215,7 +216,7 @@ module Kward
     end
 
     def post_form(uri, params)
-      request = Net::HTTP::Post.new(uri)
+      request = Http.apply_user_agent(Net::HTTP::Post.new(uri))
       request["Content-Type"] = "application/x-www-form-urlencoded"
       request.body = URI.encode_www_form(params)