kward 0.80.0 → 0.81.0

data/doc/shell.md

@@ -1,246 +1,263 @@
 # Embedded shell
 
-Use `/shell` when you want to run a sequence of local commands without leaving Kward's interactive TUI.
+Kward lets you run your own shell commands without leaving the interactive TUI. Choose the workflow that matches what you are doing:
 
-`/shell` opens **ekwsh**, the embedded Kward shell. It is not a full terminal emulator. Kward keeps ownership of the composer, transcript, tab bar, and keybindings while each command runs through your normal shell one command at a time.
+- **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.
+- **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.
 
-This makes it good for:
+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.
 
-- checking Git state,
-- running focused tests,
-- inspecting files with command-line tools,
-- using project aliases,
-- keeping command output visible beside the current Kward session.
+## Run a one-off command
 
-Use `/pty <command>` when you intentionally want to hand the terminal to a full-screen interactive command such as `less`.
+Prefix a command with `!` in the normal composer:
 
-## Start shell mode
+```text
+!git status --short
+!bundle exec ruby -Itest test/test_cli.rb
+!less README.md
+```
+
+The command runs from the active workspace root and temporarily owns the terminal. When it exits, Kward restores the composer. Safe, line-oriented output from commands such as `ls` is mirrored into the transient transcript view so a repaint cannot hide it. Shell output is never added to the AI conversation or sent to the model.
+
+The line-oriented Git commands `git fetch`, `git ls-remote`, `git push`, `git remote`, and `git status` keep the composer visible as a frozen display while they run. Keyboard input still belongs to the child process. Other commands use the full-terminal handoff so full-screen programs retain the complete terminal.
+
+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, keyboard input—including Ctrl+L and Kward's tab shortcuts—belongs to the child process.
+
+Configured `ekwsh.yml` aliases also work after `!`:
+
+```yaml
+aliases:
+  glog: "git log --decorate --stat --graph"
+```
+
+```text
+!glog
+```
+
+An alias that resolves to `kward edit <filename>` opens Kward's integrated editor in the current session instead of starting a nested Kward process:
+
+```yaml
+aliases:
+  vibe: "kward edit"
+```
+
+```text
+!vibe filename.txt
+```
+
+Press Tab after `!` to complete configured aliases, executables from `PATH`, and paths from the active workspace:
+
+```text
+!git sta<Tab>
+!cat lib/kwa<Tab>
+```
+
+The completion overlay lists matching commands and paths. Press Tab repeatedly to cycle through the listed candidates.
+
+## Work in shell mode
 
-Inside interactive Kward:
+Enter the embedded shell when you expect to run several commands:
 
 ```text
 /shell
 ```
 
-The composer prompt changes to show the shell's current directory:
+The prompt changes to show the shell's current directory:
 
 ```text
 Shell ~/code/project $
 ```
 
-Type commands as you would in a normal shell:
+The directory and exported environment persist between commands:
 
 ```sh
-git status --short
-bundle exec ruby -Itest test/test_ekwsh.rb
-cd lib/kward
+cd test
 pwd
+export RAILS_ENV=test
+bundle exec ruby -Itest test_example.rb
+unset RAILS_ENV
 ```
 
-Leave shell mode with:
+Simple assignment-only commands persist too:
 
 ```sh
-exit
+FOO=bar
+printf '%s\n' "$FOO"
 ```
 
-or press Ctrl+D on an empty shell prompt.
+Leave shell mode with `exit`, `logout`, or Ctrl+D on an empty prompt.
 
-## How commands run
+`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.
 
-`ekwsh` is POSIX-oriented and runs each command through `/bin/sh` using the shell's `-c` mode by default. You can configure another POSIX-compatible shell in `ekwsh.yml`. The shell is intentionally not started as a login shell so Kward-managed environment values, such as configured PATH entries, are not overwritten by login startup files.
+## Interactive and captured commands
 
-The current directory and exported environment are tracked by Kward between commands, so this works as expected:
+External commands inside `/shell` are interactive by default:
 
 ```sh
-cd test
-pwd
-export FOO=bar
-printf '%s\n' "$FOO"
-unset FOO
+git log
+vim README.md
+ruby
+ssh example.com
 ```
 
-`cd` changes only the embedded shell's current directory. It does not change Kward's workspace root or the process directory used by the rest of Kward.
+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.
 
-Shell output streams into the transcript area as commands run, but it is not added to the AI conversation history. Simple assignment-only commands such as `FOO=bar` persist into the embedded shell environment for later commands.
+Use `capture` inside `/shell` when you want ordinary, readable output in Kward's transcript area instead of direct terminal control:
 
-Shell commands are persisted in a separate workspace-scoped shell history. They do not share the normal Kward prompt history used for chat prompts. The shell history limit is controlled by `history_limit` in `ekwsh.yml`.
+```sh
+capture git status --short
+capture bundle exec ruby -Itest test/test_ekwsh.rb
+```
 
-## Built-ins
+An `ekwsh` `capture` command:
 
-`ekwsh` handles a small set of built-ins itself:
+- does not receive keyboard input,
+- uses the timeout and output-size limit from `ekwsh.yml`,
+- preserves safe color and styling,
+- strips controls that could corrupt Kward's TUI,
+- can be cancelled with Ctrl+C.
 
-| Built-in | What it does |
-| --- | --- |
-| `cd [dir]` | Change the embedded shell directory. Supports `cd`, `cd -`, and normal relative paths. |
-| `pwd` | Print the embedded shell directory. |
-| `export KEY[=value]` | Set or mark an environment variable for later commands. `export` and `export -p` list variables. |
-| `unset KEY` | Remove an environment variable from later commands. |
-| `alias [name]` | List configured aliases, show specific configured aliases, or set `alias name=value`. |
-| `unalias name` / `unalias -a` | Remove configured aliases. |
-| `clear` | Clear Kward's visible transcript. |
-| `exit` / `logout` | Leave shell mode. |
+From the normal composer, `/capture` provides a bounded, noninteractive one-shot command using the active workspace root:
 
-Built-ins take precedence over aliases and executables.
+```text
+/capture git status --short
+```
 
-## Tabs
+It captures stdout and stderr in the transcript view, but does not inherit `/shell` state or its configured runtime limits.
 
-Shell mode is tracked per Kward tab.
+Interactive commands are not automatically timed out or output-limited. Ctrl+C is forwarded to the child.
 
-If you enter `/shell` in one tab, switch to another tab, and later switch back, that tab is still in shell mode. Its shell state and transcript snapshot are restored until you leave shell mode in that tab.
+The older `/pty <command>` slash command and `pty <command>` shell built-in remain available for compatibility, but ordinary interactive commands no longer need them.
 
-This means each tab can have its own:
+## Shell state, history, and tabs
 
-- shell current directory,
+Each Kward tab owns its `/shell` state. Switching away and back restores that tab's:
+
+- current shell directory,
 - exported environment,
-- visible shell transcript,
-- command prompt state.
+- runtime aliases,
+- shell prompt and transcript view.
 
-Kward's normal tab-switching shortcuts continue to work in shell mode. If you switch tabs while a shell command is running, Kward cancels that foreground command and requeues the tab action so the TUI can switch cleanly.
+Shell commands use a separate, workspace-scoped history rather than the normal chat-prompt history. Configure its size with `history_limit` in `ekwsh.yml`.
 
-## Tab completion
+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.
 
-Plain Tab completes shell input while in `ekwsh`.
+## Completion
 
-Completion includes:
+Press Tab in `/shell` to complete:
 
-- built-in command names,
-- configured aliases,
-- executable names from `$PATH`,
-- file paths from the shell's current directory.
+- built-in names,
+- configured and runtime aliases,
+- executables from `PATH`,
+- files and directories from the shell's current directory.
 
 Examples:
 
 ```sh
 pw<Tab>          # pwd
-ll<Tab>          # configured alias, if present
-cat lib/kw<Tab>  # path completion
-cd doc<Tab>      # directory-only completion for cd
+ll<Tab>          # configured alias
+cat lib/kw<Tab>  # path
+cd doc<Tab>      # directories only for cd
 ```
 
-Directory completions get a trailing slash. File and command completions get a trailing space when there is a single match.
-
-Paths with spaces are shell-escaped:
+Paths with spaces are escaped:
 
 ```sh
 cat my<Tab>
 # => cat my\ file.txt
 ```
 
-Quoted path tokens are completed in the same quoting style:
+Quoted paths stay quoted:
 
 ```sh
 cat "my<Tab>
 # => cat "my file.txt
 ```
 
-If there are multiple candidates, Kward applies any common prefix. When there is no longer common prefix, it prints a compact candidate list in the transcript. Command-name completion caches `$PATH` executables and refreshes when `PATH` changes through shell assignment, `export`, or `unset`.
-
-## Colors and ANSI output
-
-`ekwsh` preserves safe ANSI SGR color/style sequences in command output, such as:
-
-- colors,
-- bold,
-- dim,
-- italic,
-- underline,
-- 256-color and truecolor SGR sequences.
-
-It strips terminal-control sequences that could corrupt Kward's TUI, such as cursor movement, clear-screen controls, OSC title changes, and alternate-screen controls.
-
-When rbenv is available, `ekwsh` also prepends the rbenv shims and bin directories to PATH and sets `RBENV_ROOT` when it was missing. This lets commands such as `ruby`, `bundle`, and `./exe/kward` use the same Ruby selected by rbenv without requiring `rbenv init` support in `ekwsh`.
+When several candidates match, repeated Tab presses cycle through them and wrap back to the first. Candidate lists stay in the composer instead of being printed in the transcript. The executable cache refreshes when `PATH` changes through assignment, `export`, or `unset`.
 
-By default, `ekwsh` sets conservative color-friendly environment values:
+## Built-ins
 
-```sh
-CLICOLOR=1
-COLORTERM=truecolor
-TERM=xterm-256color  # only when TERM is missing or dumb
-```
+`ekwsh` handles a small set of commands itself so their state can persist:
 
-It does **not** force color by default. If a tool does not emit color because stdout is not a TTY, use a command-specific flag or configure forced color yourself:
+| Built-in | What it does |
+| --- | --- |
+| `cd [dir]` | Change the shell directory. Supports `cd`, `cd -`, and relative paths. |
+| `pwd` | Print the shell directory. |
+| `export KEY[=value]` | Set an environment variable. `export` and `export -p` list variables. |
+| `unset KEY` | Remove an environment variable. |
+| `alias [name]` | List, inspect, or create aliases. |
+| `unalias name` / `unalias -a` | Remove aliases. |
+| `capture <command>` | Run with bounded, sanitized transcript output. |
+| `pty <command>` | Compatibility spelling for interactive terminal handoff. |
+| `clear` | Clear the visible transcript. |
+| `exit` / `logout` | Leave shell mode. |
 
-```sh
-git diff --color=always
-grep --color=always TODO lib/**/*.rb
-```
+Built-ins take precedence over aliases and executables.
 
-## Global ekwsh config
+## Configure ekwsh
 
-You can configure environment variables and aliases in:
+Global shell configuration lives at:
 
 ```text
 ~/.kward/ekwsh.yml
 ```
 
-If `KWARD_CONFIG_PATH` points to another config file, `ekwsh.yml` is read from that file's directory instead.
+When `KWARD_CONFIG_PATH` selects another main config file, Kward reads `ekwsh.yml` from the same directory.
 
-Example:
+A practical configuration might look like this:
 
 ```yaml
 shell: /bin/sh
-# timeout_seconds: 300
-# max_output_bytes: 1048576
-# history_limit: 1000
+timeout_seconds: 300
+max_output_bytes: 1048576
+history_limit: 1000
 
 env:
   FORCE_COLOR: "1"
-  CLICOLOR_FORCE: "1"
+  BUNDLE_WITHOUT: "production"
   RAILS_ENV: "test"
 
 aliases:
   ll: "ls -la"
   gs: "git status --short"
   gd: "git diff --color=always"
+  glog: "git log --decorate --stat --graph"
   be: "bundle exec"
   t: "bundle exec ruby -Itest"
 ```
 
-### Runtime settings
-
-`ekwsh` accepts these top-level runtime settings:
+### Settings
 
 | Setting | Default | What it does |
 | --- | --- | --- |
-| `shell` | `/bin/sh` | Absolute path to the POSIX-compatible shell used with `-c`. Invalid or relative paths fall back to `/bin/sh`. |
-| `timeout_seconds` | `300` | Maximum runtime for one command. |
-| `max_output_bytes` | `1048576` | Maximum captured output for one command. |
-| `history_limit` | `1000` | Maximum persisted shell history entries per workspace. |
+| `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. |
+| `history_limit` | `1000` | Maximum shell-history entries per workspace. |
 
-When a command exceeds `timeout_seconds`, `ekwsh` terminates it and reports the timeout. When command output exceeds `max_output_bytes`, `ekwsh` terminates the command, keeps bounded output, and reports the output limit. Press Ctrl+C while a command is running to terminate that command and return to the shell prompt without exiting Kward.
+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.
 
-### Environment variables
+### Environment
 
-`env` values are applied when shell mode starts, after Kward's conservative color defaults.
+Configured `env` values are applied when `/shell` starts. Keys must be valid environment-variable names; nil values and invalid keys are ignored, and other values are converted to strings.
 
-Keys must look like environment variable names:
+Kward also supplies conservative terminal defaults:
 
-```text
-A_Z, digits after the first character, and underscores
-```
-
-Invalid keys are ignored. Values are converted to strings. Nil values are ignored.
-
-Configured env is useful for local preferences such as:
-
-```yaml
-env:
-  FORCE_COLOR: "1"
-  BUNDLE_WITHOUT: "production"
-  RAILS_ENV: "test"
+```sh
+CLICOLOR=1
+COLORTERM=truecolor
+TERM=xterm-256color  # only when TERM is missing or dumb
 ```
 
-For one shell session, you can also use the built-in `export` command:
+It does not force color. Set `FORCE_COLOR`, `CLICOLOR_FORCE`, or a command-specific option such as `--color=always` when needed.
 
-```sh
-export FORCE_COLOR=1
-```
+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.
 
 ### Aliases
 
-Aliases expand the first word of a command once.
-
-With this config:
+Aliases replace the first command word once and append any remaining arguments:
 
 ```yaml
 aliases:
@@ -248,8 +265,6 @@ aliases:
   t: "bundle exec ruby -Itest"
 ```
 
-these commands run as:
-
 ```sh
 ll lib
 # runs: ls -la lib
@@ -258,75 +273,25 @@ t test/test_ekwsh.rb
 # runs: bundle exec ruby -Itest test/test_ekwsh.rb
 ```
 
-Aliases are intentionally simple:
-
-- only the first word is expanded,
-- aliases do not recursively expand,
-- built-ins win over alias names,
-- aliases are not shell functions,
-- aliases are global for now.
-
-List configured aliases inside `ekwsh`:
-
-```sh
-alias
-```
-
-Show specific aliases:
-
-```sh
-alias ll gs
-```
-
-Aliases also appear in command-name Tab completion.
-
-## Interactive PTY passthrough
-
-Use `/pty <command>` for commands that need to own the terminal temporarily, such as pagers:
-
-```text
-/pty git log
-```
-
-Inside `/shell`, use the `pty` built-in so the command inherits the embedded shell's current directory and environment:
-
-```sh
-pty git log
-pty vim README.md
-```
-
-Kward runs the command in a PTY, forwards your keyboard input to the process, and streams the process output directly to the terminal. This lets tools such as `less` receive keys like Space, `/`, `n`, and `q` normally. When the command exits, Kward restores its prompt and records only a short session summary in the transcript instead of raw full-screen terminal control output.
-
-`/pty` and shell `pty` are explicit on purpose. Normal `/shell` commands remain captured and transcript-friendly; `pty` is for commands where the child process should temporarily own the terminal.
+Configured aliases work inside `/shell` and after `!`. Aliases created with the `alias` built-in belong only to the current `/shell` session and are not shared with one-shot `!command` input.
 
-## `/shell` versus `!command`
-
-Kward has two ways to run local commands yourself:
-
-```text
-!git status --short
-```
+For compatibility with older configs, Kward removes a leading `pty` or `capture` mode marker when a configured alias is invoked through `!`, because `!command` is always interactive.
 
-runs one command directly from the normal composer.
+Aliases are intentionally simple: they do not expand recursively and are not shell functions. Use `alias` to list them, `alias name=value` to create a runtime alias, and `unalias` to remove one.
 
-```text
-/shell
-```
+## Terminal output and safety
 
-starts an embedded command mode for several commands with persistent shell state, aliases, completion, and per-tab shell context.
+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.
 
-Use `!command` for one-offs. Use `/shell` when you expect to run several commands in a row.
+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` is deliberately not a full interactive terminal.
-
-Current limitations:
-
-- no job control,
-- no persistent shell functions,
-- no shell startup file sourcing,
-- no native readline from your login shell,
-- normal `/shell` command output is transcript-sanitized rather than treated as a full terminal UI.
+`ekwsh` manages shell-like state, but it is not a persistent login shell or terminal emulator:
 
-External `/shell` commands run under a minimal PTY so terminal-aware tools can detect TTY output and terminal width. Full-screen interactive programs should still use explicit `/pty <command>` passthrough.
+- 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,
+- 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.

data/doc/skills.md

@@ -70,19 +70,31 @@ Project-level skills live in the current workspace:
 
 The `.agents/skills` paths are the cross-client Agent Skills convention. Use them when you want skills to work across compatible agents.
 
-Project skills are skipped by default because repository-provided instructions may be untrusted. If you trust the repository, enable project skills from inside Kward:
+Project skills require an explicit trust decision because repository-provided instructions may be untrusted. In the interactive TUI, Kward asks when it finds a new or changed project skill:
 
 ```text
-/settings
+Allow / Deny / Review
 ```
 
-Then choose:
+`Review` displays the bounded `SKILL.md` contents and lists referenced resources without executing them. Trust decisions are scoped to the current workspace and skill snapshot. A changed skill or newly added skill requires another decision. Use `/new` after changing trust for the active agent to rebuild.
+
+You can inspect or manage the current workspace from the TUI:
 
 ```text
-Tools & Search → Trust project skills
+/skills status
+/skills trust
+/skills untrust
 ```
 
-Or set it manually:
+For non-interactive use, inspect or manage trust explicitly:
+
+```bash
+kward --working-directory /path/to/project skills status
+kward --working-directory /path/to/project skills review
+kward --working-directory /path/to/project skills trust
+```
+
+Trust records are stored in `~/.kward/trusted_project_skills.json`. The legacy global setting remains available:
 
 ```json
 {
@@ -92,6 +104,8 @@ Or set it manually:
 }
 ```
 
+In the interactive TUI, skipped or malformed skill diagnostics are shown as synchronized `Runtime>` messages so they do not interrupt screen rendering. Other interactive warnings use the same channel; non-interactive commands continue to report diagnostics on stderr.
+
 ## How Kward uses skills
 
 Kward uses progressive loading:

data/doc/tabs.md

@@ -61,7 +61,7 @@ Inspect, merge, or remove the binding explicitly:
 
 Removal refuses a dirty worktree and keeps its branch. A worktree that is missing or no longer points at the recorded branch is restored as unavailable rather than silently falling back to the original workspace.
 
-Worktree tabs are available for normal session tabs, not plugin-owned tabs. Kward's file tools, `@`/`$` completion, `/files` browser, integrated editor, and model-requested shell workers use the active worktree root. Model operations retain strict workspace guardrails. The interactive `/shell`, `!command`, and `/pty` features remain user-controlled and are not contained by the model command sandbox; use them only when that is intentional. Generic shell Git writes remain protected. When explicitly asked to commit, the agent can use the active tab's narrow `git_commit` tool; use the interactive `/git` flow when you want to review and commit changes yourself.
+Worktree tabs are available for normal session tabs, not plugin-owned tabs. Kward's file tools, `@`/`$` completion, `/files` browser, integrated editor, and model-requested shell workers use the active worktree root. Model operations retain strict workspace guardrails. The user-directed `/shell`, `!command`, `/capture`, and `/pty` features remain host-process operations and are not contained by the model command sandbox; use them only when that is intentional. Generic shell Git writes remain protected. When explicitly asked to commit, the agent can use the active tab's narrow `git_commit` tool; use the interactive `/git` flow when you want to review and commit changes yourself.
 
 ## Common workflow
 

data/doc/usage.md

@@ -66,7 +66,7 @@ Inside interactive mode, ask Kward to run a command:
 Run the focused test for the CLI status command.
 ```
 
-Or run a shell command yourself from the composer by prefixing it with `!`:
+Or run an interactive PTY command yourself from the composer by prefixing it with `!`. Aliases configured in `ekwsh.yml` are expanded here too:
 
 ```text
 !git status --short
@@ -78,7 +78,7 @@ For several commands, enter the embedded Kward shell:
 /shell
 ```
 
-`/shell` opens `ekwsh`, a Kward-native command mode that keeps the tab bar and transcript visible. It preserves state such as the current directory, environment variables, and aliases between commands. Use `pty git log` or `/pty git log` when you intentionally want to hand the terminal to an interactive tool such as `less` or `vim`. See [Embedded shell](shell.md) for built-ins, completion, configuration, ANSI handling, PTY passthrough, and limitations.
+`/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 commands
 
@@ -123,8 +123,9 @@ 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 workspace commands in the embedded Kward shell. |
-| `/pty <command>` | hand the terminal to an interactive command such as `git log`/`less` or `vim`. |
+| `/shell` | run stateful workspace commands with interactive PTY support. |
+| `/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. |
 | `/status` | see session, model, and context status. |
 | `/new` | start a fresh session in the current tab. |
@@ -168,7 +169,7 @@ Prompt templates, configured skills, and plugins can add more slash commands. Th
 
 ## Prompt history
 
-The [Interactive composer](composer.md) guide covers multiline editing, slash and file completion, reasoning shortcuts, busy input, cancellation, attachments, and terminal compatibility.
+The [Interactive composer](composer.md) guide covers multiline editing, slash and file completion, reasoning selection, busy input, cancellation, attachments, and terminal compatibility.
 
 In interactive mode, Kward keeps prompt history per workspace under `~/.kward/history/`. Press Up/Down to recall previous prompts across restarts.
 

data/lib/kward/agent.rb

@@ -28,11 +28,12 @@ module Kward
   # lowest layer that owns the behavior, and use `Agent` only for cross-step turn
   # coordination.
   class Agent
-    def initialize(client:, tool_registry: ToolRegistry.new, conversation: Conversation.new, telemetry_logger: TelemetryLogger.new, hook_manager: nil, hook_context: nil)
+    def initialize(client:, tool_registry: ToolRegistry.new, conversation: Conversation.new, telemetry_logger: nil, warning_sink: nil, hook_manager: nil, hook_context: nil)
       @client = client
       @tool_registry = tool_registry
       @conversation = conversation
-      @telemetry_logger = telemetry_logger
+      @warning_sink = warning_sink
+      @telemetry_logger = telemetry_logger || TelemetryLogger.new(warning_sink: warning_sink)
       @hook_manager = hook_manager
       @hook_context = hook_context
     end
@@ -191,9 +192,9 @@ module Kward
 
     def auto_compact_if_needed
       context_window = @client.current_context_window if @client.respond_to?(:current_context_window)
-      Compactor.new(conversation: @conversation, client: @client).auto_compact_if_needed(context_window: context_window)
+      Compactor.new(conversation: @conversation, client: @client, warning_sink: @warning_sink).auto_compact_if_needed(context_window: context_window)
     rescue StandardError => e
-      warn "Auto-compaction failed: #{e.message}"
+      emit_warning "Auto-compaction failed: #{e.message}"
       nil
     end
 
@@ -201,14 +202,18 @@ module Kward
       settings = Compaction::Settings.from_config
       return nil unless settings.enabled
 
-      Compactor.new(conversation: @conversation, client: @client, settings: settings).compact(
+      Compactor.new(conversation: @conversation, client: @client, settings: settings, warning_sink: @warning_sink).compact(
         custom_instructions: "The previous model request exceeded the context window. Preserve the current task state and critical details needed to retry."
       )
     rescue Compaction::NothingToCompact, Compaction::AlreadyCompacted, StandardError => compaction_error
-      warn "Context overflow recovery failed: #{compaction_error.message}; original error: #{error.message}"
+      emit_warning "Context overflow recovery failed: #{compaction_error.message}; original error: #{error.message}"
       nil
     end
 
+    def emit_warning(message)
+      @warning_sink ? @warning_sink.call(message) : warn(message)
+    end
+
     def chat(on_reasoning_delta: nil, on_retry: nil, cancellation: nil, steering: nil, options: {}, tool_registry: nil)
       reasoning_delta = lambda do |delta|
         cancellation&.raise_if_cancelled!