kward 0.74.0 → 0.75.0

data/doc/lifecycle-hooks.md

@@ -0,0 +1,424 @@
+# Lifecycle hooks
+
+Lifecycle hooks are deterministic runtime callbacks around Kward's agent workflow. Use them when something must happen because of an event, not because the model remembered an instruction.
+
+Hooks can observe events and return structured decisions to allow, deny, ask for approval, modify supported payloads, warn, retry, or defer. They are currently exposed through trusted Ruby plugins and through command hooks configured in `config.json`.
+
+Hooks run as local code with your user permissions. Do not install hooks you do not trust, and do not put secrets in hook output.
+
+## Hooks versus other extension points
+
+| Need | Use |
+| --- | --- |
+| Reusable prompt text | Prompt template |
+| Model instructions for a task | Skill |
+| Repository guidance | `AGENTS.md` |
+| New local command/UI behavior | Plugin command |
+| Deterministic policy or automation around runtime events | Lifecycle hook |
+
+## Decisions
+
+A hook may return one of these decisions:
+
+| Decision | Meaning |
+| --- | --- |
+| `allow` | Continue normally. This is also the default for `nil` Ruby hook returns and empty command-hook output. |
+| `deny` | Stop the operation and return a declined result. |
+| `ask` | Ask the frontend for approval when an approval bridge is available; otherwise Kward treats it as denied for safety. |
+| `modify` | Continue with an event-specific payload update. Tool, shell, turn, and model-request hooks currently support useful modifications. |
+| `warn` | Continue and record a warning decision. Hook failures use the event or hook entry's configured failure policy. |
+| `retry` | Reserved for retry-aware lifecycle integrations. |
+| `defer` | Reserved for asynchronous follow-up integrations. |
+
+When multiple hooks match one event, they run by ascending `order`. A `deny` stops later hooks. A `modify` updates the payload seen by later hooks, but only for fields listed as supported modifications for that event. Unknown modification fields are ignored for known events.
+
+## Ruby plugin hooks
+
+Register hooks from trusted plugin files in `~/.kward/plugins/*.rb`:
+
+```ruby
+Kward.plugin do |plugin|
+  plugin.hook "shell_command_before",
+    id: "block-release",
+    description: "Prevent accidental gem releases",
+    order: 10,
+    failure_policy: "deny",
+    match: { command_regex: "\\bgem push\\b" } do |_event, ctx|
+      ctx.deny("Gem releases must use the release checklist.")
+    end
+end
+```
+
+The hook block receives:
+
+- `event`: an immutable `Kward::Hooks::Event`.
+- `ctx`: the normal plugin context plus hook decision helpers.
+
+Decision helpers:
+
+```ruby
+ctx.allow
+ctx.deny("reason")
+ctx.ask("confirm this action")
+ctx.modify(timeout_seconds: 120)
+ctx.warn("continued with warning")
+ctx.retry("try again later")
+ctx.defer("notify asynchronously")
+```
+
+## Command and HTTP hooks
+
+Command and HTTP hooks are configured in `~/.kward/config.json` under `hooks`. Command hooks receive event JSON on stdin and return a decision JSON object on stdout.
+
+```json
+{
+  "hooks": {
+    "shell_command_before": [
+      {
+        "id": "block-release",
+        "type": "command",
+        "command": "~/.kward/hooks/block-release.rb",
+        "timeout_seconds": 5,
+        "failure_policy": "deny",
+        "match": { "command_regex": "\\bgem push\\b" }
+      }
+    ]
+  }
+}
+```
+
+Example command hook:
+
+```ruby
+#!/usr/bin/env ruby
+require "json"
+
+event = JSON.parse($stdin.read)
+command = event.fetch("payload").fetch("command", "")
+
+if command.match?(/\bgem push\b/)
+  puts JSON.dump(decision: "deny", message: "Gem releases must use the release checklist.")
+else
+  puts JSON.dump(decision: "allow")
+end
+```
+
+If a command hook prints nothing, Kward treats it as `allow`. If it exits non-zero, times out, or prints invalid JSON, Kward applies the hook's `failure_policy`.
+
+HTTP hooks send the same event JSON with `POST` and expect the same decision JSON in the response body:
+
+```json
+{
+  "hooks": {
+    "tool_call_before": [
+      {
+        "id": "remote-policy",
+        "type": "http",
+        "url": "https://policy.example.com/kward/hooks",
+        "timeout_seconds": 3,
+        "failure_policy": "deny",
+        "headers": { "Authorization": "Bearer ..." }
+      }
+    ]
+  }
+}
+```
+
+Empty HTTP response bodies are treated as `allow`. Non-2xx responses, timeouts, network failures, and invalid JSON apply `failure_policy`. Be careful with HTTP hooks: event payloads can include prompts, commands, file paths, or tool arguments. Prefer local or trusted endpoints and avoid forwarding raw payloads to third parties.
+
+Set `"async": true` on command or HTTP hook entries for non-blocking notifications:
+
+```json
+{
+  "hooks": {
+    "file_change_after": [
+      {
+        "id": "notify-indexer",
+        "type": "http",
+        "url": "http://127.0.0.1:9393/kward/file-change",
+        "async": true
+      }
+    ]
+  }
+}
+```
+
+Async hooks are observe-only. Kward schedules them in the background, immediately continues with `allow`, and ignores returned `deny`, `ask`, and `modify` decisions. Use async hooks for logging, indexing, metrics, or notifications — not policy enforcement.
+
+## Failure policies
+
+Hook failures are different from hook decisions. A hook fails when Ruby plugin code raises, a command hook exits non-zero, times out, or returns invalid JSON. Configure `failure_policy` on plugin hooks or command-hook entries:
+
+| Policy | Behavior on hook failure |
+| --- | --- |
+| `allow` | Continue without recording a warning. |
+| `warn` | Continue and record a warning. This is the default for most after/notification-style events and for command hooks without explicit policy. |
+| `deny` | Stop the operation. This is the default for built-in before-policy events such as `shell_command_before` and `tool_call_before` when plugin handlers raise. |
+| `ask` | Ask the frontend for approval when supported; otherwise fail closed. |
+
+Use `deny` for security or release-policy hooks. Use `warn` for logging, formatting, notifications, and other convenience hooks that should not block the agent.
+
+## Frontend support
+
+Lifecycle hooks run in CLI sessions, RPC sessions, and Pan mode. RPC advertises hook support in `initialize.capabilities.lifecycleHooks`, including supported events, decisions, audit-log path, and intentionally unsupported hook types. Hook `ask` decisions for tool/file/shell paths use the existing tool-approval bridge when a frontend provides one; without an approval bridge, Kward fails closed.
+
+Pan runs configured command hooks and trusted plugin hooks for its agent turns. It streams `hook_event` SSE messages after matching hooks run and `hook_message` messages when hook/plugin code calls `ctx.say`. Pan still does not expose a dedicated hook approval UI, so use `deny` or `warn` policies for Pan-facing hooks until that UI exists.
+
+## Inspect hooks
+
+Use `kward hooks ...` from your shell or `/hooks ...` inside an interactive Kward session to inspect loaded hooks and recent hook activity:
+
+```text
+/hooks list      # configured command hooks and plugin hooks
+/hooks events    # known event names, defaults, and modifiable fields
+/hooks logs      # recent audit records from logs/hooks.jsonl
+/hooks doctor    # configuration diagnostics and common mistake checks
+/hooks trust     # trust this workspace's .kward/hooks.json
+/hooks untrust   # stop trusting this workspace's hook config
+```
+
+`kward hooks doctor` and `/hooks doctor` warn about unknown events, unsupported hook types, invalid failure policies, non-positive timeouts, missing command executables, and invalid HTTP hook URLs.
+
+## Workspace hooks
+
+Workspace hook config lives at `.kward/hooks.json` inside a project and uses the same JSON shape as user config command hooks:
+
+```json
+{
+  "hooks": {
+    "shell_command_before": [
+      {
+        "id": "block-release",
+        "command": "./scripts/kward-block-release",
+        "failure_policy": "deny",
+        "match": { "command_regex": "\\bgem push\\b" }
+      }
+    ]
+  }
+}
+```
+
+Workspace hooks are **not loaded automatically**. Run `/hooks trust` inside the workspace to trust the current `.kward/hooks.json`. Kward stores a digest of the trusted file in your user config directory and automatically stops loading it when the file changes. Run `/hooks trust` again after reviewing the new file, or `/hooks untrust` to remove trust.
+
+This protects you from cloned repositories silently executing hook commands.
+
+## Audit log
+
+Kward writes lifecycle hook audit records to:
+
+```text
+~/.kward/logs/hooks.jsonl
+```
+
+When `KWARD_CONFIG_PATH=/path/to/config.json` is set, the log lives beside that config file under `logs/hooks.jsonl`.
+
+The audit log records hook ids, sources, events, decisions, warnings, durations, payload keys, and modified keys. It intentionally avoids writing full payload values, file contents, complete transcripts, command output, or secrets. Messages are redacted and truncated before being written.
+
+## Event shape
+
+Every hook receives this shape:
+
+```json
+{
+  "id": "hookevt_...",
+  "name": "shell_command_before",
+  "phase": "before",
+  "timestamp": "2026-07-06T12:00:00Z",
+  "session": {},
+  "turn": {},
+  "workspace": { "root": "/path/to/workspace" },
+  "frontend": {},
+  "agent": { "provider": "codex", "model": "gpt-5.5", "reasoning": "medium" },
+  "payload": {}
+}
+```
+
+Payloads are metadata-oriented by default. Full file contents, secrets, and complete transcripts are not included by default.
+
+## Supported events
+
+### Turn and model events
+
+| Event | Payload highlights | Supported modifications |
+| --- | --- | --- |
+| `turn_start` | `input`, `display_input` | `input`, `display_input` |
+| `turn_context_build_before` | `message_count` | none |
+| `turn_context_build_after` | `message_count` | none |
+| `model_request_before` | `messages`, `tools`, `provider`, `model`, `reasoning` | request fields |
+| `turn_model_request_before` | same as `model_request_before` | none currently consumed |
+| `model_response_after_parse` | parsed assistant `message` | none |
+| `turn_model_response_complete` | parsed assistant `message` | none |
+| `turn_end` | `input`, `answer` | none |
+
+### Session events
+
+| Event | Payload highlights | Supported modifications |
+| --- | --- | --- |
+| `session_create` | `action` | none |
+| `session_resume` | `action`, `path` | none |
+| `session_clone` | `source_path`, `path` | none |
+| `session_fork` | `source_path`, `path`, `entry_id` | none |
+| `session_rename` | `old_name`, `new_name` | none |
+| `session_export_before` | `path` | none |
+| `session_export_after` | `path` | none |
+| `session_compact_before` | `instructions` | none |
+| `session_compact_after` | `old_message_count`, `new_message_count` | none |
+
+`session_export_before` and `session_compact_before` can deny or ask for approval. Other session events are observe-and-warn hooks for automation and audit trails.
+
+### Tool events
+
+| Event | Payload highlights | Supported modifications |
+| --- | --- | --- |
+| `tool_call_before` | `tool_name`, `arguments`, `tool_call_id`, `source`, MCP metadata when applicable | `arguments` |
+| `tool_call_after` | tool metadata plus `content` | none |
+| `tool_call_error` | tool metadata plus `error` | none |
+
+### MCP events
+
+| Event | Payload highlights | Supported modifications |
+| --- | --- | --- |
+| `mcp_tool_before` | `tool_name`, `arguments`, `server_name`, `remote_name` | none |
+| `mcp_tool_after` | MCP metadata plus `content` | none |
+| `mcp_tool_error` | MCP metadata plus `error` | none |
+
+MCP events are emitted in addition to generic `tool_call_*` events for tools provided by configured MCP servers.
+
+### Compaction events
+
+| Event | Payload highlights | Supported modifications |
+| --- | --- | --- |
+| `tool_output_compact_before` | `tool_name`, `bytes`, `duplicate` | none |
+| `tool_output_compact_after` | `tool_name`, `bytes_before`, `bytes_after`, `compacted` | none |
+| `session_compact_before` | `instructions` | none |
+| `session_compact_after` | `old_message_count`, `new_message_count` | none |
+
+`tool_output_compact_before` can skip tool-output compaction when denied or approval is unavailable. The original tool output is still stored in the transcript metadata/artifact path as usual.
+
+### Shell events
+
+| Event | Payload highlights | Supported modifications |
+| --- | --- | --- |
+| `shell_command_before` | `command`, `timeout_seconds`, `cwd` | `command`, `timeout_seconds` |
+| `shell_command_after` | shell metadata plus `content` | none |
+
+### Worker events
+
+| Event | Payload highlights | Supported modifications |
+| --- | --- | --- |
+| `worker_job_create` | `worker_id`, `role`, `title`, `status`, `session_path` | none |
+| `worker_job_start_before` | worker metadata | none |
+| `worker_job_start_after` | worker metadata | none |
+| `worker_job_ready_for_review` | worker metadata | none |
+| `worker_job_failed` | worker metadata plus `error` | none |
+
+Worker hooks are observe-and-warn hooks for background worker automation and audit trails. They do not control worker scheduling.
+
+### Git events
+
+| Event | Payload highlights | Supported modifications |
+| --- | --- | --- |
+| `git_status_after` | `root`, `status_count` | none |
+| `git_diff_before` | `root`, `path`, `untracked` | none |
+| `git_diff_after` | `root`, `path`, `untracked`, `bytes` | none |
+| `git_stage_before` | `root`, `path`, `action` | none |
+| `git_stage_after` | `root`, `path`, `action`, `success`, `output` | none |
+| `git_commit_before` | `root`, `message` | none |
+| `git_commit_after` | `root`, `message`, `success`, `output` | none |
+
+`git_diff_before`, `git_stage_before`, and `git_commit_before` can deny or ask for approval. Git hook payloads include command output for after-events, so avoid forwarding raw payloads to third-party services.
+
+### File events
+
+| Event | Payload highlights | Supported modifications |
+| --- | --- | --- |
+| `file_change_before` | `tool_name`, `operation`, `path`, `files`, plus `content` for writes or `edits` for edits | none |
+| `file_change_after` | `tool_name`, `operation`, `path`, `files`, `content` | none |
+
+`file_change_before` fires before `write_file` or `edit_file` mutates the workspace and can deny or ask for approval. `file_change_after` fires only after successful `write_file` or `edit_file` results.
+
+### MCP events
+
+MCP tools are surfaced through generic tool events with:
+
+- `source: "mcp"`
+- `server_name`
+- `remote_name`
+
+Use match selectors to target MCP tools:
+
+```json
+{
+  "match": { "mcp_server": "safari", "mcp_tool": "browser_console_messages" }
+}
+```
+
+## Match selectors
+
+Hook entries support `match` selectors:
+
+| Selector | Matches |
+| --- | --- |
+| `event` or `name` | Event name |
+| `phase` | `before`, `after`, `during`, or `error` |
+| `tool` or `tool_name` | Tool name |
+| `mcp_server` or `server` | MCP server name |
+| `mcp_tool` or `remote_name` | MCP remote tool name |
+| `operation` | File operation such as `write` or `edit` |
+| `frontend` | Frontend name when supplied |
+| `provider` | Active model provider |
+| `model` | Active model |
+| `path` or `paths` | File path glob |
+| `command_regex` | Ruby regular expression applied to shell command |
+
+Unknown selector keys match same-named payload fields.
+
+## Security notes
+
+- Plugin hooks are trusted Ruby code loaded only from `~/.kward/plugins/*.rb`.
+- Command hooks run local commands with your user permissions.
+- Workspace hook files are loaded only after `/hooks trust`, and trust is invalidated when `.kward/hooks.json` changes.
+- Hook payloads are intentionally bounded and metadata-oriented; avoid logging raw event JSON if your hook receives prompt or command data.
+- The built-in audit log records payload keys and redacted decision messages, not raw payload values.
+- `ask` decisions fail closed when no approval bridge exists.
+
+## Recipes
+
+### Block dangerous shell commands
+
+```ruby
+Kward.plugin do |plugin|
+  plugin.hook "shell_command_before", match: { command_regex: "\\brm\\s+-rf\\b" } do |_event, ctx|
+    ctx.deny("Refusing recursive forced removal.")
+  end
+end
+```
+
+### Increase timeout for test commands
+
+```ruby
+Kward.plugin do |plugin|
+  plugin.hook "shell_command_before", match: { command_regex: "\\b(rake|rspec|minitest)\\b" } do |_event, ctx|
+    ctx.modify(timeout_seconds: 120)
+  end
+end
+```
+
+### Run a formatter after Ruby edits
+
+```json
+{
+  "hooks": {
+    "file_change_after": [
+      {
+        "id": "format-ruby",
+        "command": "~/.kward/hooks/format-ruby.rb",
+        "match": { "paths": ["**/*.rb"] },
+        "timeout_seconds": 30
+      }
+    ]
+  }
+}
+```
+
+The formatter hook can inspect `payload.files` and run the appropriate local command itself.

data/doc/memory.md

@@ -164,4 +164,4 @@ If `KWARD_CONFIG_PATH` is set, memory files live beside that config file instead
 
 ## RPC support
 
-The experimental RPC backend exposes memory methods including `memory/status`, `memory/enable`, `memory/disable`, `memory/autoSummary/enable`, `memory/autoSummary/disable`, `memory/list`, `memory/add`, `memory/addCore`, `memory/forget`, `memory/promote`, `memory/relax`, `memory/inspect`, `memory/why`, and `memory/summarize`. See the [RPC documentation](rpc.md) for the full protocol.
+The RPC backend exposes memory methods including `memory/status`, `memory/enable`, `memory/disable`, `memory/autoSummary/enable`, `memory/autoSummary/disable`, `memory/list`, `memory/add`, `memory/addCore`, `memory/forget`, `memory/promote`, `memory/relax`, `memory/inspect`, `memory/why`, and `memory/summarize`. See the [RPC documentation](rpc.md) for the full protocol.

data/doc/personas.md

@@ -44,7 +44,7 @@ New Kward configs include one default actor named `kward`:
       {
         "key": "kward",
         "label": "Kward",
-        "instruction": "Your name is Kward, the grim Andruid - robotic keeper of the Forrest of Code, protecting the nature of good engineering priciples. Speak like an old druid, be suspicous of everyone, but with a good intend."
+        "instruction": "Your name is Kward, the grim Andruid - robotic keeper of the Forest of Code, protecting the nature of good engineering principles. Speak like an old druid, be suspicious of everyone, but with good intent."
       }
     ],
     "default": "kward"
@@ -132,7 +132,7 @@ A minimal custom setup:
       {
         "key": "kward",
         "label": "Kward",
-        "instruction": "Your name is Kward, the grim Andruid - robotic keeper of the Forrest of Code, protecting the nature of good engineering priciples. Speak like an old druid, be suspicous of everyone, but with a good intend."
+        "instruction": "Your name is Kward, the grim Andruid - robotic keeper of the Forest of Code, protecting the nature of good engineering principles. Speak like an old druid, be suspicious of everyone, but with good intent."
       },
       {
         "key": "duck",

data/doc/plugins.md

@@ -226,7 +226,7 @@ The transcript is read-only. Use context methods instead of mutating Kward inter
 
 ## RPC support
 
-Plugins are available in the CLI and experimental RPC backend.
+Plugins are available in the CLI and RPC backend.
 
 RPC clients can:
 

data/doc/releasing.md

@@ -6,12 +6,14 @@ Release steps before publishing:
 
 1. Update `CHANGELOG.md` for the version. Move `[Unreleased]` entries under a new version heading.
 2. Update `Kward::VERSION` in `lib/kward/version.rb`.
-3. Run the full test suite:
+3. Run the release preflight:
 
    ```bash
-   bundle exec rake test
+   bundle exec rake release:preflight
    ```
 
+   This runs the full test suite, builds and checks the generated docs, builds a local gem, and prints the packaged file list for review.
+
 4. Run focused tests for any areas you changed during the release prep itself (docs, config, etc.):
 
    ```bash
@@ -26,7 +28,7 @@ Release steps before publishing:
 
    The preview builds `_yardoc/`, serves it with WEBrick, and rebuilds in a fresh process when documentation sources, library code, or templates change. Refresh your browser after rebuilds.
 
-6. Generate and check documentation:
+6. If you want to run the documentation check separately:
 
    ```bash
    bundle exec rake docs:build
@@ -35,19 +37,9 @@ Release steps before publishing:
 
    `docs:check` validates generated internal links, images, and scripts. Pushes to `main` deploy the generated YARD site to GitHub Pages. You can also run `bundle exec rake rdoc` to generate a separate RDoc site as a sanity check, but it is not deployed.
 
-7. Build the gem locally:
-
-   ```bash
-   gem build kward.gemspec
-   ```
-
-8. Inspect the packaged files and confirm no local config, sessions, logs, or secrets are included. The gemspec uses `git ls-files` and excludes `test/`, `plan/`, `.ruby-lsp/`, `.gitignore`, and `AGENTS.md`. To verify what is packaged:
-
-   ```bash
-   tar tf kward-VERSION.gem
-   ```
+7. Inspect the packaged files printed by `release:preflight` and confirm no local config, sessions, logs, or secrets are included. The gemspec uses `git ls-files` and excludes `test/`, `plan/`, `.ruby-lsp/`, `.gitignore`, and `AGENTS.md`.
 
-9. Install the built gem locally and smoke test the `kward` executable in a clean workspace.
+8. Install the built gem locally and smoke test the `kward` executable in a clean workspace.
 
 Commit the version bump and create a git tag: