@scotthuang/agent-knock-knock 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.6.2 - 2026-07-31
+
+### Changed
+
+- Publish `AKK list` action contract v2 with machine-readable field semantics that distinguish managed task lifecycle, terminal process liveness, parsed screen activity, deprecated compatibility flags, and the authoritative `available_actions` snapshot.
+
+### Fixed
+
+- Recognize both current `»` and legacy `›` Codex composer markers across idle detection, approval parsing, stale-prompt rejection, completion boundaries, and terminal artifact cleanup while preserving fail-closed working and approval precedence.
+
 ## 0.6.1 - 2026-07-30
 
 ### Added

package/README.md

@@ -197,7 +197,7 @@ The core command surface is intentionally small:
 
 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. Before every terminal operation, AKK revalidates the expected agent PID and tmux pane identity, then confirms that the process and pane working directories still match; every send also revalidates the idle prompt immediately before typing.
 
-For natural-language tool use, `agent_knock_knock_list` returns an `available_actions` object on rows in `delegated[]` and `terminal_controlled[]`; `tasks[]` remains a compatibility summary. Use only an action shown there, start with its prefilled authoritative arguments, and supply every `missing_required` field. `send` uses `selector`; status, approval, cancellation, renewal, callback retry, and close use `conversation_id`. For an ordinary send, add only `request`—`timeoutSeconds` is not a supported argument, and monitoring limits should be omitted unless the user explicitly asks to change them.
+For natural-language tool use, `agent_knock_knock_list` returns an `available_actions` object on rows in `delegated[]` and `terminal_controlled[]`; `tasks[]` remains a compatibility summary. Use only an action shown there, start with its prefilled authoritative arguments, and supply every `missing_required` field. A delegated row's `status` is its task lifecycle, while a terminal-controlled row's `status` only says whether the coding-agent process is alive and its `activity_state` reports the parsed screen state. The legacy `commands` flags have mixed compatibility semantics, are deprecated, and must never drive tool calls; `available_actions` is the only authoritative current-action source. `send` uses `selector`; status, approval, cancellation, renewal, callback retry, and close use `conversation_id`. For an ordinary send, add only `request`—`timeoutSeconds` is not a supported argument, and monitoring limits should be omitted unless the user explicitly asks to change them.
 
 Workspace is not a routing boundary. AKK can list, inspect, and control verified panes across projects; when more than one target matches, use a selector to choose one explicitly.
 

package/dist/src/cli.js

@@ -1640,13 +1640,34 @@ function managedListApprovalState(conversation) {
 }
 function listActionContracts() {
     return {
-        version: 1,
+        version: 2,
         instructions: [
             "Use only actions present in delegated[].available_actions or terminal_controlled[].available_actions.",
+            "Never use commands for routing or tool calls. It is a deprecated, non-authoritative compatibility field with mixed legacy semantics.",
             "Start with the action's prefilled arguments, supply every missing_required field, and consult the top-level action's optional fields only when needed.",
             "Authoritative full IDs are prefilled; short_ref is for display and human input.",
             "Availability is a snapshot. AKK revalidates process, tmux pane, workspace, activity, approval, and recovery state before side effects."
         ],
+        field_semantics: {
+            status: {
+                delegated: "task_lifecycle",
+                terminal_controlled: "process_liveness",
+                authoritative_for_tool_calls: false
+            },
+            activity_state: {
+                terminal_controlled: "screen_activity_classification",
+                authoritative_for_tool_calls: false
+            },
+            commands: {
+                meaning: "legacy_compatibility_flags_with_mixed_semantics",
+                deprecated: true,
+                authoritative_for_tool_calls: false
+            },
+            available_actions: {
+                meaning: "currently_safe_actions",
+                authoritative_for_tool_calls: true
+            }
+        },
         actions: {
             send: {
                 tool: "agent_knock_knock_send",