@scotthuang/agent-knock-knock 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.5.1 - 2026-07-29
+
+### Changed
+
+- Put one complete ClawHub-first path from installation through workspace setup, Gateway restart, tmux startup, diagnostics, and the first task at the top of the README.
+- Separate direct `/akk` usage from optional natural-language tool access and keep the npm installer as an alternative path.
+
+### Fixed
+
+- Fail closed with actionable setup guidance when the plugin workspace is missing or non-absolute instead of falling back to the Gateway working directory.
+- Keep `/akk doctor` available to diagnose invalid workspace configuration.
+
+## 0.5.0 - 2026-07-29
+
+### Changed
+
+- Make already-running, verified-idle Codex and Claude Code tmux panes the only delegation targets.
+- Resolve bare `/akk <task>` only when exactly one eligible idle pane exists in the configured workspace, and use `/akk <selector>: <message>` for an explicit target.
+- Enforce the configured workspace as a hard boundary even for explicit terminal IDs and recovery operations.
+- Keep the main command surface focused on task routing, listing, status, and cancellation; keep diagnostics, approvals, and recovery operations in their relevant workflows.
+
+### Removed
+
+- Remove configuration-based default-agent routing and the `--default-agent` installer option.
+- Remove obsolete session inspection and attachment surfaces from the user-facing workflow.
+
 ## 0.4.0 - 2026-07-29
 
 ### Changed

package/README.md

@@ -9,11 +9,46 @@ Agent Knock Knock lets OpenClaw control local Codex and Claude Code through shar
 
 **No hooks. No agent-side plugins. Just share a terminal and stay in control. No YOLO. Automate the trusted. Review the rest.**
 
+## Quick Start with ClawHub
+
+AKK reuses Codex or Claude Code already running in tmux; it never launches a coding agent. You need OpenClaw `2026.6.5`+, tmux, and an authenticated `codex` or `claude` CLI, all running as the same OS user.
+
+From the project AKK may edit:
+
+```bash
+cd /absolute/path/to/project
+openclaw plugins install clawhub:@scotthuang/agent-knock-knock
+openclaw config set plugins.entries.agent-knock-knock.config.workspace "$(pwd -P)"
+openclaw gateway restart
+```
+
+Start the shared coding-agent terminal:
+
+```bash
+tmux new-session -s akk-work -c "$(pwd -P)" codex
+```
+
+Use `claude` instead of `codex` if preferred. Wait for the coding agent's idle prompt, then detach from tmux with `Ctrl-b`, followed by `d`.
+
+From any configured OpenClaw channel, first send:
+
+```text
+/akk doctor
+```
+
+After doctor reports `AKK doctor: ready`, send a separate message:
+
+```text
+/akk inspect this repository and summarize it
+```
+
+The second command proves that AKK can find the pane, send work in the configured workspace, and return the result. Direct `/akk ...` commands need no OpenClaw tool-policy changes.
+
 ## See It in Action
 
 [![AKK orchestrating a Claude Code-to-Codex handoff through tmux](https://raw.githubusercontent.com/scotthuang/agent-knock-knock/main/docs/assets/akk-tmux-handoff-demo.gif)](https://github.com/scotthuang/agent-knock-knock/blob/main/docs/assets/akk-tmux-handoff-demo.mp4)
 
-*OpenClaw asks Claude Code to write a file, waits for AKK to report completion, then hands the result to Codex. Both terminals remain available for direct human takeover. AKK keeps the agents' existing permission settings. Click the preview to watch in full quality.*
+*OpenClaw asks Claude Code to write a file, waits for AKK to report completion, then hands the result to Codex. Both terminals remain available for direct human control. AKK keeps the agents' existing permission settings. Click the preview to watch in full quality.*
 
 ## Use Cases
 
@@ -35,7 +70,26 @@ AKK connects OpenClaw to Codex or Claude Code already running inside tmux:
 
 AKK is local-first. It has no hosted control plane or telemetry and does not change the coding agent's configured permission mode.
 
-## Install
+## Optional: Natural-Language Delegation
+
+The quick start uses direct `/akk ...` commands, which bypass the model and work without plugin tool access. To let OpenClaw decide to use AKK from a natural-language request, grant the optional `agent-knock-knock` tools in the applicable tool policy.
+
+If you use the default `coding` profile and do not already have `tools.allow`, add AKK without replacing the profile:
+
+```json5
+{
+  tools: {
+    profile: "coding",
+    alsoAllow: ["agent-knock-knock"]
+  }
+}
+```
+
+If your configuration already has a restrictive `tools.allow` list, add `"agent-knock-knock"` to that existing list instead. Do not set `allow` and `alsoAllow` at the same scope.
+
+Restart the Gateway after changing the tool policy.
+
+## Installation Details
 
 Requirements:
 
@@ -53,48 +107,22 @@ Requirements:
 
 The compatibility suite tests the normal installation floor and the Plugin API boundary with isolated state and the real packed artifact.
 
-### Install from ClawHub (recommended)
-
-From the project the agents may edit:
-
-```bash
-openclaw plugins install clawhub:@scotthuang/agent-knock-knock
-openclaw config set plugins.entries.agent-knock-knock.config.workspace "$PWD"
-openclaw config set plugins.entries.agent-knock-knock.config.defaultAgent codex
-openclaw gateway restart
-```
-
-Use `claude` instead of `codex` when preferred.
-
 ClawHub installs the OpenClaw plugin, bundled AKK skill, and package-local relay CLI together. It does not add the `agent-knock-knock` command to your shell `PATH`. Do not run `install-openclaw` after a ClawHub install; that command belongs to the npm path below.
 
-AKK's plugin tools are optional OpenClaw tools and require an explicit tool-policy grant. If you use the default `coding` profile and do not already have `tools.allow`, add AKK without replacing the profile:
-
-```json5
-{
-  tools: {
-    profile: "coding",
-    alsoAllow: ["agent-knock-knock"]
-  }
-}
-```
-
-If your configuration already has a restrictive `tools.allow` list, add `"agent-knock-knock"` to that existing list instead. Do not set `allow` and `alsoAllow` at the same scope.
-
 If you also want standalone shell commands such as `agent-knock-knock doctor`, install the npm package globally without running `install-openclaw`:
 
 ```bash
 npm install -g @scotthuang/agent-knock-knock
 ```
 
-### Install from npm
+### Alternative: Install from npm
 
 ```bash
 npm install -g @scotthuang/agent-knock-knock
-agent-knock-knock install-openclaw --workspace "$PWD" --default-agent codex --verify
+agent-knock-knock install-openclaw --workspace "$(pwd -P)" --verify
 ```
 
-`install-openclaw` installs or updates the plugin, configures the workspace and default agent without replacing unrelated settings, installs the bundled skill, restarts the Gateway at most once, and optionally verifies the runtime chain. It is safe to rerun. Without `--verify`, the result remains unverified rather than claiming readiness. Use `--skill-only` to skip plugin installation; add `--no-restart` to leave an explicit pending-restart state.
+`install-openclaw` installs or updates the plugin, configures the workspace without replacing unrelated settings, installs the bundled skill, restarts the Gateway at most once, and optionally verifies the runtime chain. It is safe to rerun. Without `--verify`, the result remains unverified rather than claiming readiness. Use `--skill-only` to skip plugin installation; add `--no-restart` to leave an explicit pending-restart state.
 
 If OpenClaw runs from a local checkout or another nonstandard location, pass its CLI explicitly:
 
@@ -102,7 +130,7 @@ If OpenClaw runs from a local checkout or another nonstandard location, pass its
 agent-knock-knock install-openclaw --openclaw-bin /path/to/openclaw/openclaw.mjs
 ```
 
-## Start the Shared Terminal
+## Shared Terminal Details
 
 Install tmux on macOS:
 
@@ -119,7 +147,7 @@ sudo apt-get install tmux
 Then start Codex in a shared terminal:
 
 ```bash
-tmux new-session -s akk-work -c "$PWD" codex
+tmux new-session -s akk-work -c "$(pwd -P)" codex
 ```
 
 Use `claude` instead of `codex` for Claude Code. Detach with `Ctrl-b`, then `d`. AKK discovers the pane automatically.
@@ -142,51 +170,45 @@ For one complete first run, follow [Agent Knock Knock in 5 minutes](https://gith
 
 ## Usage
 
-Use conversational `AKK` prompts on any chat surface. Explicit agent names override the configured default:
+AKK sends work only to Codex or Claude Code panes that are already running in tmux, inside the configured workspace, and at a verified idle prompt. It never starts a coding agent for you.
+
+If exactly one idle coding-agent pane matches the workspace, send a task directly:
 
 ```text
-AKK Codex: inspect this repository and summarize it
-AKK Claude: review the latest commit
-AKK describe latest
+/akk inspect this repository and summarize it
 ```
 
-Surfaces with native commands use the same operations:
+If more than one pane is available, name the target before the colon:
+
+```text
+/akk codex: inspect this repository and summarize it
+/akk claude: review the latest commit
+/akk @a1b2c3d4: run the focused tests
+```
+
+The core command surface is intentionally small:
 
 ```text
 /akk <task>
+/akk <selector>: <message>
 /akk list
-/akk doctor
 /akk status [only|latest|codex|claude|@short-ref]
-/akk describe [session-selector]
-/akk send <session-selector>: <message>
-/akk approve <session-selector> --expected-approval-fingerprint <fingerprint>
 /akk cancel <session-selector>
-/akk renew <session-selector> [minutes]
-/akk retry-callback <session-selector>
-/akk close <session-selector> [--expected-message-id <id>] [reason]
 ```
 
-Selectors fail closed: `only` works only with one actionable target, `latest` requires a unique newest target, and an agent name must identify exactly one actionable session. `AKK list` shows stable short references while JSON output retains the authoritative full IDs.
-
-You can also send directly to a terminal entry returned by `AKK list`:
-
-```text
-AKK send codex: continue with the smaller implementation
-AKK send @a1b2c3d4: run the focused tests
-```
+Selectors fail closed: `only` works only with one actionable target, `latest` requires a unique newest target, and `codex` or `claude` must identify exactly one eligible pane. `AKK list` shows stable short references while JSON output retains the authoritative full IDs. Every send revalidates the pane, process, workspace, and idle state immediately before typing.
 
-AKK submits only when the selected pane is at a verified idle prompt. If no eligible Codex or Claude Code tmux pane is available, it stops and tells you how to start one instead of launching an invisible replacement.
+The configured workspace is a hard boundary for OpenClaw tools and slash commands. Listing, inspection, sending, approval, cancellation, and recovery do not cross into another workspace even when given an explicit terminal ID.
 
-If `AKK list` reports an orphaned terminal dispatch after its managed state was lost, inspect the named pane first. Clear only that stale dispatch fence with the exact `/akk close ... --expected-message-id ...` recovery command returned by the list; AKK leaves both the coding agent and tmux pane running.
+If no eligible pane exists, AKK stops with setup guidance. If a send is ambiguous, run `/akk list` and retry with the returned `@short-ref`.
 
 ## Configuration
 
-AKK reads these options from `plugins.entries.agent-knock-knock.config`. The npm installer writes the common options; the ClawHub section shows the equivalent setup.
+AKK reads these options from `plugins.entries.agent-knock-knock.config`. The npm installer writes the common options; the ClawHub quick start shows the equivalent manual setup.
 
 | Option | Default | Purpose |
 | --- | --- | --- |
-| `defaultAgent` | `codex` | Agent used when a request does not name one: `codex` or `claude`. |
-| `workspace` | OpenClaw process directory | Working directory matched against eligible terminal panes. |
+| `workspace` | Required before use | Absolute, canonical working directory matched against eligible terminal panes. Runtime operations fail closed when it is missing. |
 | `storeDir` | `~/.agent-knock-knock/conversations` | Conversation state location; relative plugin paths resolve from `workspace`. |
 | `openclawBin` | Auto-detected | OpenClaw CLI used for callback delivery. |
 | `codexHome` | Auto-detected | Optional Codex home used to identify Codex sessions running in tmux. |
@@ -204,7 +226,7 @@ For Claude Code, manual approval is deliberately narrow:
 
 - It is available only for the current AKK-managed turn.
 - AKK accepts only an exact, current Bash dialog with the one-time **Yes** choice already highlighted, correlated to one unresolved foreground Bash tool request in the anchored owner-private transcript. Persistent permission choices are rejected.
-- When no trusted rule matches, the callback takes the manual path. The user must personally inspect the named tmux pane, explicitly confirm the exact request, and then run `AKK approve <@short-ref>`; the hash-only callback is not sufficient for review.
+- When no trusted rule matches, the callback takes the manual path. The user must personally inspect the named tmux pane, explicitly confirm the exact request, and then run `/akk approve @a1b2c3d4 --expected-approval-fingerprint <fresh-fingerprint>` using the fingerprint from that current notification; the hash-only callback is not sufficient for review.
 - AKK re-evaluates the evidence and revalidates the process and pane immediately before sending one Enter.
 
 Unknown, stale, changed, ambiguous, or unmanaged dialogs fail closed and must be resolved in the terminal.
@@ -244,6 +266,7 @@ With the global npm CLI installed, start with `agent-knock-knock doctor`. It run
 | Source changes do not appear | Build, reinstall from the checkout, and restart the Gateway. |
 | Terminal task is `stalled` | Inspect `status` and the terminal; use `/akk renew only <minutes>` only when exactly one live stalled task needs more monitoring time. |
 | Task is `callback_failed` | Run `/akk retry-callback only` when it is the only actionable failed callback, or use its `@short-ref`. |
+| `AKK list` reports an orphaned terminal dispatch | Inspect the named pane first, then run the exact `/akk close ... --expected-message-id ...` recovery command returned by `list`. AKK leaves the coding agent and tmux pane running. |
 | Claude permission is not offered through AKK | Resolve unsupported dialogs in the terminal. The AKK path requires the exact supported one-time Bash prompt for the current managed turn. |
 | Claude request was not auto-approved | Check `autoApprove.enabled`, the agent, canonical workspace, and exact command vector. The request must also have matching current screen and local transcript evidence. |
 | Claude monitor becomes `stalled` | Check the Claude version and `status`, then inspect the terminal. Unknown transcript schemas, background work, identity changes, and ambiguous turns intentionally fail closed. |