kward 0.82.0 → 0.83.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4e40d786a99770eef30a7eb7fec41470d927f9d889160d1c6db9f8fd1ebec39
-  data.tar.gz: 1cfaf680bf9b5ef313e0a0f71a3fb33ea394eb7bc2f5d19c5bfee4c38898ac49
+  metadata.gz: 678c9e9bb188e6c3d065dfde6b97c9ec5c31b29b178b40d69b0397b5200eb2a8
+  data.tar.gz: 3e09cb3d11ff6018ecc75e3eb31e8745e72e534dba7a4c3711a488451d353fcc
 SHA512:
-  metadata.gz: efe8e4a599791fee93d0329c7d0ec4e87c9d45c9ad9f99165d9172d44410ccc83de8014802cc76481d37952e89427b80cac1022a2f7fc17d0bd3c05356d44391
-  data.tar.gz: 9b1ad11cfd582d78d4834cf5b6f168ca8e2f987abe99804678d5e58c2e3000fcff6ebbf30448a71aa1f0ca7a94e9e9585be7b0643d6c88e3ed931e3ab6f3eada
+  metadata.gz: 7f4247a32300deff0906c95c10d7312aa6303108956596f16d9f2c6d2d4fc444b5ef377751f47dbd2157b041710d855c44a981a1a22f8a562c79203afe8b65ed
+  data.tar.gz: d93d09126d221c05d7ef0e931f46ccfaa4a84450e6eb5695dbea653d8b9de99bb27bc7fb070b323c74160477fd328f0be3cd972d544b45e3ea90ffbeb79cb087

data/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to Kward will be documented in this file.
 
 ## [Unreleased]
 
+## [0.83.0] - 2026-08-28
+
+### Added
+
+- Added `?` shell prompts for transient, context-aware assistance inside `/shell`, including shared shell-state commands and prepare-without-execute command drafts.
+- Added `Ctrl+.` in Modern editor mode to open an in-editor prompt line for communicating with the dedicated editor agent.
+- Added Vibe `:prompt <instruction>` support, allowing the agent to inspect and replace the active in-memory editor buffer without saving it automatically.
+- Added current-buffer word completion to the integrated editor, with repeated Tab presses cycling nearby matches and existing smart indentation retained when no match exists.
+- Added Claude Opus 5 to the Anthropic model picker with its 1M context window and high-reasoning metadata.
+- Added an `i` toggle to the `/files` browser for showing Git-ignored files, which remain hidden by default.
+
+### Changed
+
+- `/shell` now keeps one persistent local shell process per tab so shell variables, functions, aliases, and directory changes are shared by user and agent commands.
+- Shell-agent turns use a transient per-tab context and receive only bounded, sanitized output after an explicit `?` request; ordinary shell output remains outside model context.
+- Shell-agent transcript output is now retained as bounded, tab-local runtime state so it survives tab switches without entering session history.
+- Vibe editor-agent turns now use an isolated, configurable model/reasoning context, remain visible with a status-line spinner, and stay out of normal chat transcripts and session history.
+- Removed the obsolete GPT-5.6 Luna Responses Lite compatibility workaround so Luna requests retain Kward's identity and standard Codex payload.
+
+### Fixed
+
+- Made persistent shell command cancellation and timeouts recover by restarting an unresponsive embedded shell, and stabilized raw-input coverage across platforms.
+- Restored full-screen Git pagers and immediate key/Ctrl+C forwarding for interactive `/shell` commands by removing Kward's ambient `GIT_PAGER=cat` default and putting host input in raw mode during persistent-shell handoff, while keeping paging suppressed for captured and shell-agent commands.
+- Fixed Claude subscription OAuth authorization and token-exchange requests by removing unsupported subscription scopes and the nonstandard `code` query parameter, and by forwarding the OAuth state to the token endpoint.
+- Installed and enabled Bubblewrap during release verification so Linux worktree tests use the same sandbox setup as normal CI, added manual recovery for existing release tags, and made publication wait for and attach the canonical RubyGems artifact after trusted-publishing attestation.
+- Fixed automatic context compaction so Codex response items are included in token estimates and long tool-call turns are checked before each model request.
+
 ## [0.82.0] - 2026-08-23
 
 ### Added
@@ -91,6 +118,7 @@ All notable changes to Kward will be documented in this file.
 - Added Git worktree bindings for normal interactive session tabs. `/tab worktree` can move a tab into a strict linked-worktree workspace after research, preserve its transcript, warn about dirty origin changes, and keep the branch available when explicitly detached.
 - Added the active worktree `git_commit` model tool, allowing explicitly requested agent commits through the trusted host-side Git workflow without widening the shell sandbox.
 - Added `/tab worktree merge` for explicitly merging a clean worktree branch into the branch checked out in its original workspace, plus `/tab worktree merge abort` for conflicted merges.
+- Added `/worktree` as a concise alias for `/tab worktree` on the active tab.
 - Added `j`/`k` keyboard navigation to the `/files` project browser.
 - Added `h`/`l` keyboard navigation for collapsing and expanding `/files` directories.
 - Added `j`/`k` keyboard navigation to the `/git` changed-file overlay.

data/Gemfile.lock

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

data/doc/agent-tools.md

@@ -15,6 +15,7 @@ Tools also enforce important boundaries:
 | Category | Tools | Guide |
 | --- | --- | --- |
 | Workspace tools | `list_directory`, `read_file`, `context_for_task`, `context_budget_stats`, `summarize_file_structure`, `write_file`, `edit_file`, `run_shell_command` | [Workspace tools](workspace-tools.md) |
+| Shell prompt tools | `run_shell_command`, `prepare_shell_command` (available only to the transient `?` shell assistant) | [Embedded shell](shell.md) |
 | Web tools | `web_search`, `fetch_content`, `fetch_raw` | [Web search](web-search.md) |
 | Code search | `code_search` | [Code search](code-search.md) |
 | Context and interaction tools | `read_skill`, `retrieve_tool_output`, `ask_user_question` | [Context tools](context-tools.md) |

data/doc/composer.md

@@ -213,4 +213,4 @@ If rendering becomes corrupted after resize or after an external program writes
 
 You can also press `Ctrl+L`; it rebuilds the durable current-tab view without deleting the conversation transcript, removing transient shell output. If a shortcut never reaches Kward, prefer its slash-command equivalent or change `composer.tab_keybindings` in `/settings`.
 
-External commands inside `/shell` and one-shot `!command` input receive an interactive PTY by default. They begin inline above a frozen composer, then switch to full-terminal passthrough if they emit screen-oriented or unknown terminal controls; full-screen programs such as Vim or `less` can therefore temporarily own the terminal. Use `capture <command>` inside `/shell` or `/capture <command>` from the normal composer for bounded, sanitized transcript output.
+External commands inside `/shell` and one-shot `!command` input receive an interactive PTY by default. They begin inline above a frozen composer, then switch to full-terminal passthrough if they emit screen-oriented or unknown terminal controls; full-screen programs such as Vim or `less` can therefore temporarily own the terminal. While Kward owns the shell composer, a leading `?` asks the transient shell assistant; it receives only bounded, sanitized output from the latest command. Use `capture <command>` inside `/shell` or `/capture <command>` from the normal composer for bounded, sanitized transcript output.

data/doc/configuration.md

@@ -184,9 +184,9 @@ aliases:
   gd: "git diff --color=always"
 ```
 
-`env` values are applied when shell mode starts, after Kward's conservative color defaults. Keys must look like environment variable names (`A_Z`, digits after the first character, and underscores); invalid keys are ignored. Values are converted to strings.
+`env` values are applied when shell mode starts, after Kward's conservative color defaults. `/shell` keeps one persistent local interactive shell process per tab. Keys must look like environment variable names (`A_Z`, digits after the first character, and underscores); invalid keys are ignored. Values are converted to strings.
 
-`aliases` expand the first word of a command once. For example, `ll lib` runs `ls -la lib`. Configured aliases are available both inside `/shell` and after the normal composer's `!` prefix, including command-name Tab completion. Built-in `ekwsh` commands such as `cd`, `pwd`, `export`, `unset`, `alias`, `capture`, `clear`, `pty`, and `exit` take precedence over aliases inside `/shell`. External commands receive an interactive PTY by default. An alias value can begin with `capture` when its `/shell` output should use the configured timeout, output limit, and transcript sanitization. Leading-`!` alias invocations are always interactive, so Kward removes a leading `capture` or legacy `pty` mode marker from the expanded alias before execution. Run `alias` inside `ekwsh` to list configured aliases. Aliases created at runtime with that built-in belong only to the current `/shell` session and are not available to `!command` input.
+`aliases` expand the first word of a command once. For example, `ll lib` runs `ls -la lib`. Configured aliases are available both inside `/shell` and after the normal composer's `!` prefix, including command-name Tab completion. Built-in shell commands such as `cd`, `pwd`, `export`, `unset`, `alias`, `capture`, `clear`, `pty`, and `exit` take precedence over aliases inside `/shell`. External commands receive an interactive PTY by default. Prefix a submitted line with `?` inside `/shell` to ask the transient shell assistant about the current command output or state. An alias value can begin with `capture` when its `/shell` output should use the configured timeout, output limit, and transcript sanitization. Leading-`!` alias invocations are always interactive, so Kward removes a leading `capture` or legacy `pty` mode marker from the expanded alias before execution. Run `alias` inside `ekwsh` to list configured aliases. Aliases created at runtime with that built-in belong only to the current `/shell` session and are not available to `!command` input.
 
 ## Provider and model settings
 
@@ -248,7 +248,7 @@ Defaults:
 - Copilot: `gpt-5-mini`
 - Reasoning effort: `medium`
 
-The Anthropic model choices include `claude-fable-5`, but Fable availability depends on the logged-in account and organization. Selecting it without access returns an Anthropic provider error.
+The Anthropic model choices include `claude-fable-5`, `claude-opus-5`, and `claude-sonnet-5`. Fable and Opus availability depends on the logged-in account and organization. Selecting a model without access returns an Anthropic provider error. Kward keeps Sonnet 5 as its default because it supports both Pro and Max subscriptions; select Opus 5 explicitly when it is available on the account.
 
 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.
 
@@ -393,6 +393,21 @@ The built-in TUI file editor supports three keybinding modes. Modern is the defa
 
 `mode` can be `modern`, `emacs`, or `vibe`. The old `default` value is still accepted as an alias for `modern`. You can change this from `/settings` → Interface → Editor mode; newly opened editor buffers pick up the setting immediately.
 
+Vibe `:prompt` uses a dedicated transient editor agent. Configure its model and reasoning effort under `editor.agent` when it should differ from the active tab:
+
+```json
+{
+  "editor": {
+    "agent": {
+      "model": "gpt-5.5",
+      "reasoning_effort": "medium"
+    }
+  }
+}
+```
+
+These settings use the active tab's provider. If either value is omitted, Kward falls back to the active tab's value and then the client default. Editor-agent prompts and tool activity are kept out of the normal transcript and session history; the editor remains visible with a spinner while the transient turn runs.
+
 The integrated Git and session diff viewers support unified and side-by-side layouts:
 
 ```json

data/doc/editor.md

@@ -43,7 +43,7 @@ For a nested project tree, run:
 /files
 ```
 
-In the tree browser, use `↑`/`↓` to move, `←`/`→` to collapse or expand directories, `Enter` to toggle a directory or open a file, `Tab` or `/` to search, `@` to insert the selected file as an `@path` mention, and `Esc` to close. When you open a file from `/files`, quitting the editor returns to the browser at the same position.
+In the tree browser, use `↑`/`↓` to move, `←`/`→` to collapse or expand directories, `Enter` to toggle a directory or open a file, `Tab` or `/` to search, `i` to show or hide Git-ignored files, `@` to insert the selected file as an `@path` mention, and `Esc` to close. When you open a file from `/files`, quitting the editor returns to the browser at the same position.
 
 For an unsaved buffer, open a scratchpad:
 
@@ -85,21 +85,26 @@ $doc/editor.md
 1. Type `$doc/editor.md` in the composer.
 2. Pick the file from the matching results, or press `Enter` if the path is already complete.
 3. Edit the file.
-4. Save with `Ctrl+S` in Modern mode, `C-x C-s` in Emacs mode, or `:w` in Vibe mode. For an unsaved scratchpad in Vibe mode, use `:w filename`.
-5. Quit with `Ctrl+Q`, `C-x C-c`, or `:q`.
-6. Continue chatting with Kward.
+4. In Vibe normal mode, use `:prompt <instruction>` to ask the agent to update the current in-memory buffer. In Modern mode, press `Ctrl+.` and type the instruction in the editor prompt line. For example, `write a HelloWorld class`.
+5. The editor stays visible while the agent works; its status line shows a spinner. Review the generated buffer and save with `Ctrl+S` in Modern mode, `C-x C-s` in Emacs mode, or `:w` in Vibe mode. For an unsaved scratchpad in Vibe mode, use `:w filename`.
+6. Quit with `Ctrl+Q`, `C-x C-c`, or `:q`.
+7. Continue chatting with Kward.
 
 ## What the editor supports
 
 The editor is intentionally compact, but it covers the basics you need for quick changes:
 
 - Syntax highlighting for common languages, including Ruby, ERB templates, Crystal, Elixir, Julia, JavaScript, TypeScript, JSON, Markdown, YAML, Shell, Makefile, HTML, CSS, SCSS, Python, Go, Rust, Java, C#, C, C++, Swift, Kotlin, Lua, and SQL. ERB highlights template HTML outside ERB tags and Ruby inside `<% ... %>` tags. Unknown file types render as plain text.
-- Auto-indent, enabled by default. New lines inherit indentation, Tab jumps to the expected indentation or the next indentation stop, Shift+Tab moves indentation back, obvious closing tokens are re-indented, and Backspace in leading whitespace removes one indentation unit when possible. ERB recognizes common inline Ruby control tags and HTML opening tags when calculating the next indentation. For Ruby, Crystal, Elixir, Julia, Lua, Makefiles, and shell scripts, Enter after a block opener inserts the matching closing keyword; Ctrl+Enter also works from the middle of the line in terminals that report modified Enter keys.
+- Current-buffer word completion. After a partial word, Tab completes from words elsewhere in the active buffer; repeated Tab presses cycle nearby matches. Completion is case-sensitive and recognizes letters, numbers, and underscores. No project files or external sources are searched.
+- Auto-indent, enabled by default. New lines inherit indentation. When word completion does not apply, Tab jumps to the expected indentation or the next indentation stop. Shift+Tab moves indentation back, obvious closing tokens are re-indented, and Backspace in leading whitespace removes one indentation unit when possible. ERB recognizes common inline Ruby control tags and HTML opening tags when calculating the next indentation. For Ruby, Crystal, Elixir, Julia, Lua, Makefiles, and shell scripts, Enter after a block opener inserts the matching closing keyword; Ctrl+Enter also works from the middle of the line in terminals that report modified Enter keys.
 - Undo and redo, with up to 100 history entries per buffer.
 - Incremental search forward and backward.
 - Selection, copy, cut, and paste. Copy and cut also write to the terminal clipboard through OSC 52 when the terminal supports it.
 - A line-number gutter and a status line that shows the current mode and prompts.
 - Soft-wrap, enabled by default so long lines wrap within the editor width instead of scrolling sideways. Disable it with `editor.soft_wrap: false`.
+- Vibe `:prompt <instruction>` and Modern `Ctrl+.` prompt lines send the complete current buffer and document metadata to a dedicated, transient editor agent. The agent can replace the in-memory buffer through an explicit editor tool; it does not save files automatically.
+- Editor prompts and their tool activity are not added to the normal chat transcript or session history.
+- The editor remains visible and locked for editing while the agent runs. Its status line displays progress and a spinner; `Ctrl+C` cancels the request.
 
 ## Choosing an editor mode
 
@@ -122,12 +127,16 @@ You can also configure it in `config.json`:
 ```json
 {
   "editor": {
-    "mode": "modern"
+    "mode": "modern",
+    "agent": {
+      "model": "gpt-5.5",
+      "reasoning_effort": "medium"
+    }
   }
 }
 ```
 
-`mode` can be `modern`, `emacs`, or `vibe`. The old `default` value is still accepted as an alias for `modern`.
+`mode` can be `modern`, `emacs`, or `vibe`. The optional `editor.agent.model` and `editor.agent.reasoning_effort` settings configure the dedicated Vibe editor agent. They use the active tab's provider. When either value is omitted, it falls back to the active tab's setting and then the client default. Editor-agent turns use a dedicated system prompt and are not persisted in the active tab transcript. The old `default` value is still accepted as an alias for `modern`.
 
 To disable auto-indent or auto-close pairs:
 
@@ -156,6 +165,7 @@ Modern mode is the default and is the easiest place to start. It uses common ter
 | --------------------- | ------------------------------------------------- |
 | `Ctrl+S`              | Save                                              |
 | `Ctrl+Q`              | Quit; press again to discard unsaved changes      |
+| `Ctrl+.`              | Open the editor-agent prompt line                 |
 | `/`                   | Search forward                                    |
 | `?`                   | Search backward                                   |
 | `Ctrl+C`              | Copy selection, or cancel search                  |
@@ -192,7 +202,7 @@ Modern mode is the default and is the easiest place to start. It uses common ter
 | `Home` / `End`        | Move to start / end of line                       |
 | `PageUp` / `PageDown` | Scroll                                            |
 | `Enter`               | Insert newline, or confirm search                 |
-| `Tab`                 | Smart-indent to the expected indentation or next stop |
+| `Tab`                 | Complete a buffer word, or smart-indent when no match exists |
 | `Shift+Tab`           | Move indentation back by one stop                 |
 | `Backspace`           | Delete before cursor                              |
 | `Delete`              | Delete character at cursor                        |
@@ -233,7 +243,7 @@ Emacs mode is for users who prefer classic Emacs-style non-modal editing. Save a
 | `Home` / `End`        | Move to start / end of line                  |
 | `PageUp` / `PageDown` | Scroll                                       |
 | `Enter`               | Insert newline, or confirm search            |
-| `Tab`                 | Smart-indent to the expected indentation or next stop |
+| `Tab`                 | Complete a buffer word, or smart-indent when no match exists |
 | `Shift+Tab`           | Move indentation back by one stop            |
 | `Backspace`           | Delete before cursor                         |
 | `Delete` / `C-d`      | Delete character at cursor                   |
@@ -370,7 +380,7 @@ Vibe insert mode also supports readline-style shortcuts for efficient editing wi
 | ---------------- | ---------------------------------------- |
 | type text        | Insert characters                        |
 | `Enter`          | Insert newline                           |
-| `Tab`            | Smart-indent to the expected indentation or next stop |
+| `Tab`            | Complete a buffer word, or smart-indent when no match exists |
 | `Shift+Tab`      | Move indentation back by one stop        |
 | `Backspace`      | Delete before cursor                     |
 | `Delete`         | Delete character at cursor               |

data/doc/files.md

@@ -24,7 +24,7 @@ Inside a Git repository, `/files` uses Git's project view:
 git ls-files --cached --others --exclude-standard
 ```
 
-That means tracked files and normal untracked files appear, while ignored files stay out of the list.
+That means tracked files and normal untracked files appear by default, while ignored files stay out of the list. Press `i` in the tree view to show or hide Git-ignored files; Kward remembers this choice for the workspace.
 
 Outside Git, Kward scans the workspace directory and skips common noisy directories such as `.git`, `.yardoc`, `_yardoc`, `node_modules`, `rdoc`, `tmp`, and `vendor/bundle`.
 
@@ -39,6 +39,7 @@ Outside Git, Kward scans the workspace directory and skips common noisy director
 | `Tab` | Start or stop search |
 | `/` | Start search |
 | `Backspace` | Delete the last search character |
+| `i` | Show or hide Git-ignored files |
 | `Esc` | Leave search; press again to close the browser |
 | `Q` | Close an image preview |
 | `+` / `-` | Zoom an image preview in / out |
@@ -90,7 +91,7 @@ See [Integrated editor](editor.md) for editor modes, save/quit keys, search, sel
 
 ## Remembered state
 
-Kward remembers the expanded folders and selected path for each workspace. The next time you open `/files` in the same project, it restores the browser close to where you left it.
+Kward remembers the expanded folders, selected path, and Git-ignored file visibility for each workspace. The next time you open `/files` in the same project, it restores the browser close to where you left it.
 
 Search itself is temporary. Closing search returns to the normal tree, and closing the browser leaves your chat session intact.
 
@@ -103,4 +104,4 @@ Image previews are read-only and replace the file-list overlay while leaving the
 - `/files` is only available in the interactive prompt.
 - It opens files inside the current workspace.
 - It is a focused project browser, not a full file manager: it does not rename, move, copy, or delete files.
-- Ignored Git files are intentionally hidden when Git can provide the file list.
+- Ignored Git files are hidden by default when Git can provide the file list; press `i` in the tree view to show them.

data/doc/permissions.md

@@ -176,6 +176,7 @@ The policy runs before Kward dispatches a model-requested tool. It does not cons
 - 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`, `/capture`, `/shell`, and `/pty`—are treated as your actions and are outside this first policy scope;
+- commands run by the transient `?` shell assistant go through the normal permission and hook checks but deliberately use the user-owned `/shell` process, so the command sandbox cannot contain them;
 - 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.

data/doc/releasing.md

@@ -60,13 +60,21 @@ If preparation fails before the commit, the command restores the version, lockfi
 A pushed `v*` tag starts `.github/workflows/release.yml`. The workflow:
 
 1. Checks that the tag, gem version, and changelog heading agree.
-2. Runs the full test suite and generated-documentation checks against Ruby 3.4.
+2. Installs and enables Bubblewrap, then runs the full test suite and generated-documentation checks against Ruby 3.4 using the same Linux sandbox setup as normal CI.
 3. Builds the gem and verifies its packaged files.
 4. Publishes through RubyGems trusted publishing.
-5. Verifies the local gem checksum against the artifact served by RubyGems.org.
-6. Creates `Kward VERSION` as a GitHub Release using that version's changelog section and attaches the verified gem.
+5. Downloads the canonical published gem from RubyGems.org, waiting for propagation when necessary, and verifies its checksum against the RubyGems API.
+6. Creates `Kward VERSION` as a GitHub Release using that version's changelog section and attaches the verified RubyGems artifact.
 
-The publishing job uses the protected `release` environment. If RubyGems.org already has the version after a partially completed workflow, a rerun rebuilds the gem and verifies that it exactly matches the published checksum before continuing. For an existing GitHub Release, the workflow downloads and compares the gem, uploads it when missing, and publishes an unfinished draft. This makes normal workflow reruns safe without silently replacing mismatched artifacts.
+The publishing job uses the protected `release` environment. If RubyGems.org already has the version after a partially completed workflow, a rerun downloads and verifies the canonical published gem before continuing. This also accommodates trusted-publishing attestations that can change the published gem bytes. For an existing GitHub Release, the workflow downloads and compares the gem, uploads it when missing, and publishes an unfinished draft. This makes normal workflow reruns safe without silently replacing mismatched artifacts.
+
+If the workflow itself needs a fix after a tag has already been pushed, commit and push the fix to `main`, then recover the existing tag with the updated workflow:
+
+```bash
+gh workflow run Release --ref main -f tag=v0.82.0
+```
+
+Manual recovery still checks out and verifies the tagged source before publishing. The `release` environment permits automatic version-tag runs and manual recovery runs from `main` only.
 
 Follow the run from the repository's **Actions → Release** page. Installation can be checked after publication with:
 

data/doc/rpc.md

@@ -80,11 +80,11 @@ Read `capabilities` at runtime instead of assuming every feature is available. I
 - `mcp`: local stdio MCP server support through the shared `mcpServers` config. RPC exposes MCP tools to turns and advertises discovery with `methods: ["tools/list", "mcp/status"]`, `toolMetadata: true`, and `serverStatus: true`. It does not support MCP resources, prompts, sampling, or Streamable HTTP.
 - `startupResources`: supported startup resource listing for context, skills, prompts, and plugins.
 - `extensionUi`: question bridge support via `ui/question` and `ui/answerQuestion`, plus plugin footer updates via `ui/footer`; other UI primitives are explicitly unsupported.
-- `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.
+- `composer`: composer-only UI features. Interactive session diff totals are explicitly unsupported over RPC (`composer.sessionDiff.supported: false`) because RPC clients already receive per-tool diff results and no live composer status payload is exposed. Clipboard copy is also unsupported over RPC (`composer.copy.supported: false`) because UI clients own clipboard access. Vibe editor prompts are unsupported over RPC (`composer.editorPrompt.supported: false`) because RPC has no live integrated editor buffer.
 - `security`: trusted-local behavior and optional per-turn tool approval. By default, RPC turns have no workspace mutation guard or tool approval, so shell commands and file changes can run. Clients can inspect file-tool guardrails through `capabilities.events.tools.workspaceGuardrails` and `runtime/state.workspaceGuardrailsEnabled`. `security.sandbox` reports the command sandbox mode, enforcement backend, and filesystem and network capabilities; session pinning and one-time elevation are unsupported. See [Command sandboxing](sandboxing.md) for the boundary and its limits.
 - `export`: supported transcript export formats. Currently `markdown` and `html`; default is `markdown`.
 - `starterPack`: explicitly unsupported (`supported: false`, reason `cliOnlyInstallCommand`). Use `kward init` from the shell.
-- `shell`: explicitly unsupported (`supported: false`, reason `interactiveTuiOnly`) because `/shell`, `!command`, `/capture`, and PTY handoff require the local TUI. Model-requested `run_shell_command` tools remain bounded, captured, and noninteractive over RPC.
+- `shell`: explicitly unsupported (`supported: false`, reason `interactiveTuiOnly`) because `/shell`, its transient `?` shell assistant, `!command`, `/capture`, and PTY handoff require the local TUI. Model-requested `run_shell_command` tools remain bounded, captured, and noninteractive over RPC.
 - `logging`: local redacted telemetry, its directory and enabled categories, `logging/stats` and `logging/tokenCsv`, bucketed `usageCsv` support, JSONL storage, and 10 MB rotation with manual retention. Logs contain redacted metadata only. Configuration uses the `logging` key and `KWARD_LOGGING` environment prefix.
 
 ### `shutdown`

data/doc/sandboxing.md

@@ -106,12 +106,16 @@ this interface.
 ## Boundaries and limits
 
 The current implementation protects **model-requested command workers only**.
+The transient `?` shell assistant is intentionally not one of those workers: its
+`run_shell_command` calls use the active user-owned `/shell` process so shell
+state can persist.
+
 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`, `/capture`, or `/pty`.
+- MCP servers, lifecycle hooks, `/shell`, `?` shell-agent commands, `!command`, `/capture`, or `/pty`.
 
 Sandboxed command workers receive a minimal environment: Kward preserves only
 basic terminal, locale, and path variables, then supplies a private `HOME` and

data/doc/security.md

@@ -57,7 +57,7 @@ Kward's built-in file tools normally resolve paths inside the active workspace.
 These protections reduce accidental edits. They do not contain the whole process:
 
 - With `sandbox.mode: off` (the default), `run_shell_command`, `!command`, `/capture`, `/shell`, and `/pty` run with your user permissions.
-- A non-off [command sandbox](sandboxing.md) restricts only model-requested `run_shell_command` workers and their descendants. It does not cover `!command`, `/capture`, `/shell`, or `/pty`.
+- A non-off [command sandbox](sandboxing.md) restricts only model-requested `run_shell_command` workers and their descendants. It does not cover `!command`, `/capture`, `/shell`, or `/pty`, including commands that the transient `?` shell assistant runs through the user's persistent `/shell` process.
 - External `/shell` commands, `!command`, and `/pty` receive an interactive PTY. Kward forwards a conservative set of line-oriented controls into the inline region, then grants full-terminal passthrough when a child emits screen-oriented or unknown controls. Full passthrough bypasses transcript control-sequence sanitization, so run only commands you trust with terminal access. `capture <command>` and `/capture <command>` sanitize their captured output.
 - Plugins, command hooks, and MCP servers are local processes with the same general operating-system access.
 - Read-before-edit applies to Kward's file tools, not to arbitrary shell commands or extension code.

data/doc/shell.md

@@ -4,6 +4,7 @@ Kward lets you run your own shell commands without leaving the interactive TUI.
 
 - **For one quick command, use `!command`.** It runs from the active workspace and returns you to the normal composer when it finishes.
 - **For a longer stretch of shell work, use `/shell`.** It keeps its directory, environment, aliases, and history between commands.
+- **To ask Kward for help from inside `/shell`, prefix the request with `?`.** It can inspect the latest shell output, run an explicitly requested state change, or prepare a command in the shell prompt for your confirmation.
 - **For bounded output in the transcript view, use `/capture <command>`.** Inside `/shell`, use `capture <command>` for the same kind of readable output while keeping the shell's current state.
 
 Ordinary `!command` input and external commands inside `/shell` receive an interactive PTY. Pagers, Vim, SSH, REPLs, password prompts, and other interactive tools therefore work without a `pty` prefix.
@@ -20,7 +21,7 @@ Prefix a command with `!` in the normal composer:
 
 The command runs from the active workspace root and begins in an inline PTY region above a frozen composer. Line-oriented output, single-line carriage-return progress, and synchronized-output update brackets scroll the transcript area naturally while keyboard input belongs to the child process. If the child emits alternate-screen, clear-screen, absolute cursor, or unknown terminal controls, Kward conservatively hides the composer and switches permanently to full-terminal passthrough for the rest of that command. Pagers and full-screen applications therefore retain the complete terminal without relying on a command-name allowlist.
 
-When an inline command exits without reading input, safe output is mirrored into the transient transcript view so a repaint cannot hide it. Carriage-return and horizontal-cursor progress redraws are reduced to their final visible lines, while an unterminated synchronized-output update is closed before Kward redraws. If the child reads input, Kward retains only output captured before the first forwarded input byte; this prevents echoed passwords, OTPs, or other input from entering tab state. Shell output is never added to the AI conversation or sent to the model.
+When an inline command exits without reading input, safe output is mirrored into the transient transcript view so a repaint cannot hide it. Carriage-return and horizontal-cursor progress redraws are reduced to their final visible lines, while an unterminated synchronized-output update is closed before Kward redraws. If the child reads input, Kward retains only output captured before the first forwarded input byte; this prevents echoed passwords, OTPs, or other input from entering tab state. Output from one-off commands is never added to the AI conversation or sent to the model.
 
 Shell output can leave transient text in the transcript area. **After the command finishes, press Ctrl+L to redraw the durable conversation and clear that transient `!command` output.** While an interactive command is still running, the composer remains frozen and keyboard input—including Ctrl+L and Kward's tab shortcuts—belongs to the child process.
 
@@ -90,6 +91,29 @@ Leave shell mode with `exit`, `logout`, or Ctrl+D on an empty prompt.
 
 `cd` changes only the embedded shell's directory. It does not change Kward's workspace root or the directory used by the model's other tools.
 
+## Ask the shell agent
+
+While `/shell` is active, start a submitted line with `?` to ask the transient shell assistant:
+
+```text
+? why did the last command fail?
+? show me which process is listening on port 3000
+? prepare a command to find Ruby files changed today
+```
+
+The assistant receives the current shell directory, the last command, its exit status, and bounded output from that command. Output is sent to the model only because you explicitly asked with `?`; it is sanitized and bounded before being included, and shell-agent turns are not added to the normal session history.
+
+If you explicitly ask the assistant to change shell state, it can use the active shell session:
+
+```text
+? cd into test
+? set RAILS_ENV to test
+```
+
+For a suggestion or prepared command, the assistant uses `prepare_shell_command`. The command is placed in the shell composer but is not run until you press `Enter`. Running a command directly and preparing one are deliberately separate actions.
+
+The shell assistant cannot safely run commands that require terminal input. Ask it to prepare those commands instead. The local `/shell` session keeps one interactive shell process alive, so directory changes, variables, functions, aliases, and other shell state persist between commands. The one-off `!command` and `/capture` workflows remain separate. SSH remains available through the normal interactive PTY handoff, but shell-agent prompting resumes after that SSH session exits.
+
 ## Interactive and captured commands
 
 External commands inside `/shell` are interactive by default:
@@ -101,7 +125,7 @@ ruby
 ssh example.com
 ```
 
-Kward gives each command the terminal, forwards keyboard input, and restores the shell prompt when the command exits. It prints the submitted command but no PTY start message or exit-status summary. The line-oriented Git commands `git fetch`, `git ls-remote`, `git push`, `git remote`, and `git status` keep the shell prompt visible as a frozen display. Safe, line-oriented output from commands that did not read keyboard input is kept in the transient transcript view; full-screen and genuinely interactive output stays terminal-owned.
+Kward gives each command the terminal, forwards keyboard input, and restores the shell prompt when the command exits. Interactive commands inherit your normal pager configuration, so commands such as `git log` can open `less` in full-screen mode. Kward suppresses Git paging only for noninteractive shell-agent and `capture` executions. It prints the submitted command but no PTY start message or exit-status summary. The line-oriented Git commands `git fetch`, `git ls-remote`, `git push`, `git remote`, and `git status` keep the shell prompt visible as a frozen display. Safe, line-oriented output from commands that did not read keyboard input is kept in the transient transcript view; full-screen and genuinely interactive output stays terminal-owned.
 
 Use `capture` inside `/shell` when you want ordinary, readable output in Kward's transcript area instead of direct terminal control:
 
@@ -141,7 +165,7 @@ Each Kward tab owns its `/shell` state. Switching away and back restores that ta
 
 Shell commands use a separate, workspace-scoped history rather than the normal chat-prompt history. Configure its size with `history_limit` in `ekwsh.yml`.
 
-Kward's tab shortcuts work at the shell prompt and while a captured command is running. During an interactive command, the child owns every key; exit or interrupt it before switching Kward tabs.
+Kward's tab shortcuts work at the shell prompt and while a captured command is running. During an interactive command, the child owns every key; exit or interrupt it before switching Kward tabs. Bounded output from shell-agent `?` turns is also retained in the tab's transient runtime view, so it is restored when you switch away and back without being added to session history. Ctrl+L clears this transient shell and shell-agent output.
 
 ## Completion
 
@@ -179,7 +203,7 @@ When several candidates match, repeated Tab presses cycle through them and wrap
 
 ## Built-ins
 
-`ekwsh` handles a small set of commands itself so their state can persist:
+The persistent `/shell` process handles these commands in-session so their state can persist:
 
 | Built-in | What it does |
 | --- | --- |
@@ -232,12 +256,12 @@ aliases:
 
 | Setting | Default | What it does |
 | --- | --- | --- |
-| `shell` | `/bin/sh` | POSIX-compatible shell used with `-c`. It must be an absolute executable path. |
-| `timeout_seconds` | `300` | Maximum runtime for one captured command. |
-| `max_output_bytes` | `1048576` | Maximum output retained for one captured command. |
+| `shell` | `/bin/sh` | Absolute executable path for the persistent `/shell` process and interactive shell commands. |
+| `timeout_seconds` | `300` | Maximum runtime for one captured or shell-agent command. |
+| `max_output_bytes` | `1048576` | Maximum output retained for one captured or shell-agent command. |
 | `history_limit` | `1000` | Maximum shell-history entries per workspace. |
 
-Invalid or relative `shell` paths fall back to `/bin/sh`. These timeout and output limits apply only to `capture` inside `/shell`, not interactive commands or the separate `/capture` slash command.
+Invalid or relative `shell` paths fall back to `/bin/sh`. These timeout and output limits apply to `capture` inside `/shell` and shell-agent commands, not user-owned interactive commands or the separate `/capture` slash command.
 
 ### Environment
 
@@ -253,7 +277,7 @@ TERM=xterm-256color  # only when TERM is missing or dumb
 
 It does not force color. Set `FORCE_COLOR`, `CLICOLOR_FORCE`, or a command-specific option such as `--color=always` when needed.
 
-When rbenv is available, Kward adds its shims and bin directories to `PATH` and supplies `RBENV_ROOT` if it was missing. This lets `ruby`, `bundle`, and `./exe/kward` use the selected Ruby without sourcing shell startup files.
+When rbenv is available, Kward adds its shims and bin directories to `PATH` and supplies `RBENV_ROOT` if it was missing before starting `/shell`. The configured interactive shell may also load its normal startup files.
 
 ### Aliases
 
@@ -281,17 +305,17 @@ Aliases are intentionally simple: they do not expand recursively and are not she
 
 ## Terminal output and safety
 
-Interactive commands write directly to your terminal so full-screen tools can work. When a command does not read keyboard input and emits only line-oriented text plus safe color sequences, Kward mirrors that output into the transient transcript view after the command exits. Other interactive output is not sanitized and may contain terminal control sequences, so run only commands you trust with terminal access.
+Interactive commands write directly to your terminal so full-screen tools can work. When a command does not read keyboard input and emits only line-oriented text plus safe color sequences, Kward mirrors that output into the transient transcript view after the command exits. Other interactive output is not sanitized and may contain terminal control sequences, so run only commands you trust with terminal access. Safe bounded output is included in a shell-agent request only when you explicitly use `?`; it is never sent to the model for ordinary shell commands.
 
 Commands run with `capture` inside `/shell` preserve safe ANSI color and style sequences while removing cursor movement, clear-screen controls, title changes, alternate-screen controls, and similar sequences that could damage the TUI transcript.
 
 ## Limitations
 
-`ekwsh` manages shell-like state, but it is not a persistent login shell or terminal emulator:
+The local `/shell` session is persistent, but it is not a complete terminal emulator or a remote-shell protocol:
 
-- each external command runs separately through the configured shell,
-- there is no job control; a stopped child is terminated rather than leaving the terminal stranded,
-- shell functions do not persist and shell startup files are not sourced,
-- there is no login-shell readline integration,
+- the one-off `!command` and `/capture` workflows do not share `/shell` state,
+- shell state is held by the live process and is not serialized across Kward restarts,
+- a stopped or unresponsive command can still require Ctrl+C or shell-session cleanup,
 - full-screen terminal state is not retained after an interactive command exits,
-- safe line-oriented output may remain in the transient TUI transcript, but full-screen terminal state is not retained and no shell output becomes part of the AI conversation.
+- while an interactive SSH session owns the terminal, Kward cannot safely intercept `?` or provide remote cwd/completion context; shell-agent prompting resumes after SSH exits,
+- safe line-oriented output may remain in the transient TUI transcript; only bounded safe output from an explicit `?` request enters the transient shell-agent context and none of it is added to the normal session history.

data/doc/tabs.md

@@ -39,6 +39,8 @@ A normal session tab can be activated in a linked Git worktree after you have re
 
 ```text
 /tab worktree
+# or
+/worktree
 ```
 
 When enabled, Kward keeps the same tab and transcript but rebuilds its agent against a new worktree. The tab label includes the worktree branch. The worktree is created from `HEAD`, so Kward warns when the original workspace is dirty and leaves those existing changes in the original checkout; it does not copy them automatically. `/tab worktree activate` is an explicit alias for the same action.
@@ -98,6 +100,7 @@ Tabs keep the conversations separate, so context from one tab does not automatic
 | `/tab worktree merge` | Merge the current worktree branch into the branch checked out in its original workspace |
 | `/tab worktree merge abort` | Abort a conflicted worktree merge in the original workspace |
 | `/tab worktree remove` | Remove a clean linked worktree and keep its branch |
+| `/worktree …` | Alias for `/tab worktree …` on the active tab |
 | `/tab move left` | Move the current tab one slot left |
 | `/tab move right` | Move the current tab one slot right |
 | `/tab move <number>` | Move the current tab to a numbered position |

data/doc/usage.md

@@ -78,7 +78,7 @@ For several commands, enter the embedded Kward shell:
 /shell
 ```
 
-`/shell` opens `ekwsh`, a Kward-native command mode that preserves state such as the current directory, environment variables, and aliases between commands. External commands receive an interactive PTY by default, so `git log`, `less`, Vim, SSH, and REPLs work without a prefix. Use `capture <command>` inside `/shell` or `/capture <command>` from the normal composer for bounded, transcript-friendly output. See [Embedded shell](shell.md) for built-ins, completion, configuration, ANSI handling, PTY passthrough, and limitations.
+`/shell` opens `ekwsh`, a Kward-native command mode with one persistent local shell process. It preserves state such as the current directory, environment variables, functions, and aliases between commands. Prefix a line with `?` inside `/shell` to ask a transient shell assistant about the latest output, execute an explicit state change, or prepare a command without running it. External commands receive an interactive PTY by default, so `git log`, `less`, Vim, SSH, and REPLs work without a prefix. Use `capture <command>` inside `/shell` or `/capture <command>` from the normal composer for bounded, transcript-friendly output. See [Embedded shell](shell.md) for built-ins, completion, configuration, ANSI handling, PTY passthrough, and limitations.
 
 ## Shell commands
 
@@ -123,7 +123,7 @@ Slash commands run local actions in the current session. Most do not send a prom
 | `/git` | review uncommitted changes, stage files, and commit. |
 | `/diff` | open the file changes recorded in the current session. |
 | `/files` | browse project files in a nested tree and open them in the editor. |
-| `/shell` | run stateful workspace commands with interactive PTY support. |
+| `/shell` | run stateful workspace commands with interactive PTY support and ask the shell agent with `?`. |
 | `/capture <command>` | run a bounded one-shot command and retain its output in the transcript. |
 | `/pty <command>` | explicitly hand the terminal to an interactive command; retained for compatibility with existing workflows. |
 | `/settings` | configure models, accounts, memory, interface, tools, context, personalization, and logging. |
@@ -143,6 +143,7 @@ Slash commands run local actions in the current session. Most do not send a prom
 | `/tab worktree merge` | merge a clean worktree branch into the branch checked out in its original workspace. |
 | `/tab worktree merge abort` | abort a conflicted worktree merge in the original workspace. |
 | `/tab worktree remove` | remove a clean linked worktree while keeping its branch. |
+| `/worktree …` | alias for `/tab worktree …` on the active tab. |
 | `/session` | open the saved sessions picker or continue a previous session by path. |
 | `/resume` | alias for `/session`. |
 | `/session name <name>` | name or clear the current session. |

data/lib/kward/agent.rb

@@ -84,6 +84,7 @@ module Kward
       end
       loop do
         cancellation&.raise_if_cancelled!
+        auto_compact_if_needed
         begin
           message = chat(on_reasoning_delta: on_reasoning_delta, on_retry: on_retry, cancellation: cancellation, steering: steering, options: options, tool_registry: tool_registry) do |event|
             yield event if block_given?

data/lib/kward/auth/anthropic_oauth.rb

@@ -17,7 +17,7 @@ module Kward
     DEFAULT_PORT = 53_692
     CALLBACK_PATH = "/callback"
     DEFAULT_CLIENT_ID = Base64.decode64("OWQxYzI1MGEtZTYxYi00NGQ5LTg4ZWQtNTk0NGQxOTYyZjVl")
-    SCOPE = "org:create_api_key user:profile user:inference user:sessions:claude_code user:mcp_servers user:file_upload"
+    SCOPE = "user:profile user:inference user:sessions:claude_code user:mcp_servers user:file_upload"
 
     attr_reader :auth_path
 
@@ -60,7 +60,7 @@ module Kward
       end
       raise "Missing authorization code" if code.to_s.empty?
 
-      complete_login_flow(code: code, redirect_uri: redirect_uri, code_verifier: pkce[:verifier])
+      complete_login_flow(code: code, redirect_uri: redirect_uri, code_verifier: pkce[:verifier], state: state)
       auth_path
     ensure
       server&.close unless server&.closed?
@@ -68,7 +68,6 @@ module Kward
 
     def authorization_url(redirect_uri:, code_challenge:, state:)
       query = URI.encode_www_form(
-        code: "true",
         client_id: client_id,
         response_type: "code",
         redirect_uri: redirect_uri,
@@ -98,8 +97,8 @@ module Kward
       wait_for_callback(server, expected_state: expected_state, timeout_seconds: timeout_seconds)
     end
 
-    def complete_login_flow(code:, redirect_uri:, code_verifier:)
-      tokens = exchange_code_for_tokens(code: code, redirect_uri: redirect_uri, code_verifier: code_verifier)
+    def complete_login_flow(code:, redirect_uri:, code_verifier:, state:)
+      tokens = exchange_code_for_tokens(code: code, redirect_uri: redirect_uri, code_verifier: code_verifier, state: state)
       save_auth(tokens: tokens)
       tokens
     end
@@ -192,13 +191,14 @@ module Kward
       oauth_callback_server(port_env: "KWARD_ANTHROPIC_OAUTH_PORT", default_port: DEFAULT_PORT)
     end
 
-    def exchange_code_for_tokens(code:, redirect_uri:, code_verifier:)
+    def exchange_code_for_tokens(code:, redirect_uri:, code_verifier:, state:)
       response = post_json(TOKEN_URL,
         grant_type: "authorization_code",
         client_id: client_id,
         code: code,
         redirect_uri: redirect_uri,
-        code_verifier: code_verifier)
+        code_verifier: code_verifier,
+        state: state)
       parse_successful_json(response, "Anthropic OAuth token exchange")
     end