@scotthuang/agent-knock-knock 0.6.2 → 0.8.0

package/dist/src/openclaw-plugin.js

@@ -6,6 +6,7 @@ import { AKK_CALLBACK_METHOD, akkUsageText, buildAkkCommandCliArgs, formatAkkLis
 import { attemptAutoApproval } from "./approval-policy.js";
 const CALLBACK_METHOD = AKK_CALLBACK_METHOD;
 const defaultBinPath = fileURLToPath(new URL("./cli.js", import.meta.url));
+const relayPathByApi = new WeakMap();
 const sendParameters = {
     type: "object",
     additionalProperties: false,
@@ -25,7 +26,7 @@ const sendParameters = {
         },
         idleTimeoutMinutes: {
             type: "number",
-            description: "Minutes an idle AKK session remains open before lazy cleanup closes it."
+            description: "Minutes an idle AKK session remains open before controlled reconciliation closes its managed-turn record."
         },
         agentTimeoutMinutes: {
             type: "number",
@@ -52,13 +53,9 @@ const listParameters = {
         all: {
             type: "boolean"
         },
-        managedOnly: {
-            type: "boolean",
-            description: "When true, only list AKK-managed turns and skip live tmux terminal discovery."
-        },
         noApprovalScan: {
             type: "boolean",
-            description: "When true, list terminal-controlled sessions without scanning terminal panes for approval prompts."
+            description: "When true, list live terminals without scanning their panes for approval prompts."
         },
         terminalDebug: {
             type: "boolean",
@@ -103,7 +100,7 @@ const statusParameters = {
     properties: {
         conversation_id: {
             type: "string",
-            description: "AKK-managed conversation id, or a terminal-controlled id from AKK list such as terminal:v2:tmux:codex:codex-work:0.1:33389."
+            description: "Managed-turn conversation id, or a live terminal id from AKK list such as terminal:v2:tmux:codex:codex-work:0.1:33389."
         },
         idleTimeoutMinutes: {
             type: "number"
@@ -121,7 +118,7 @@ const cancelParameters = {
     properties: {
         conversation_id: {
             type: "string",
-            description: "AKK-managed conversation id, or a terminal-controlled id from AKK list such as terminal:v2:tmux:codex:codex-work:0.1:33389."
+            description: "Managed-turn conversation id, or a live terminal id from AKK list such as terminal:v2:tmux:codex:codex-work:0.1:33389."
         },
         idleTimeoutMinutes: {
             type: "number"
@@ -152,7 +149,7 @@ const approveParameters = {
     properties: {
         conversation_id: {
             type: "string",
-            description: "AKK-managed conversation id, or a terminal-controlled id from AKK list such as terminal:v2:tmux:codex:codex-work:0.1:33389."
+            description: "Managed-turn conversation id, or a live terminal id from AKK list such as terminal:v2:tmux:codex:codex-work:0.1:33389."
         },
         expected_approval_fingerprint: {
             type: "string",
@@ -160,171 +157,175 @@ const approveParameters = {
         }
     }
 };
-const plugin = definePluginEntry({
-    id: "agent-knock-knock",
-    name: "Agent Knock Knock",
-    description: "Agent Knock Knock (AKK/akk) lets OpenClaw operate local Codex and Claude Code through shared tmux terminals, with visible monitoring, approvals, callbacks, cancellation, and seamless human takeover.",
-    register(api) {
-        api.registerGatewayMethod(CALLBACK_METHOD, async ({ params, respond }) => {
+function createPlugin(relayPath) {
+    return definePluginEntry({
+        id: "agent-knock-knock",
+        name: "Agent Knock Knock",
+        description: "Agent Knock Knock (AKK/akk) lets OpenClaw operate local Codex and Claude Code through shared tmux terminals, with visible monitoring, approvals, callbacks, cancellation, and seamless human takeover.",
+        register(api) {
+            relayPathByApi.set(api, relayPath);
+            api.registerGatewayMethod(CALLBACK_METHOD, async ({ params, respond }) => {
+                try {
+                    const result = await handleCallback(api, params);
+                    respond(true, result);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    api.logger.warn?.(`agent-knock-knock callback failed: ${message}`);
+                    respond(false, undefined, {
+                        code: "AGENT_KNOCK_KNOCK_CALLBACK_FAILED",
+                        message
+                    });
+                }
+            }, { scope: "operator.write" });
             try {
-                const result = await handleCallback(api, params);
-                respond(true, result);
+                api.registerService?.({
+                    id: "agent-knock-knock-monitor-reconciliation",
+                    start() {
+                        try {
+                            const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+                            const args = ["reconcile-monitors"];
+                            pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
+                            const result = runCli(api, args);
+                            api.logger.info?.("agent-knock-knock monitor reconciliation: " +
+                                `checked=${result.checked ?? 0} launched=${result.launched ?? 0} ` +
+                                `already_running=${result.already_running ?? 0} skipped=${result.skipped ?? 0} ` +
+                                `errors=${result.errors ?? 0}`);
+                        }
+                        catch (error) {
+                            const message = error instanceof Error ? error.message : String(error);
+                            api.logger.warn?.(`agent-knock-knock monitor reconciliation skipped after startup error: ${message}`);
+                        }
+                    }
+                });
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                api.logger.warn?.(`agent-knock-knock callback failed: ${message}`);
-                respond(false, undefined, {
-                    code: "AGENT_KNOCK_KNOCK_CALLBACK_FAILED",
-                    message
-                });
+                api.logger.warn?.(`agent-knock-knock monitor reconciliation service was not registered: ${message}`);
             }
-        }, { scope: "operator.write" });
-        try {
-            api.registerService?.({
-                id: "agent-knock-knock-monitor-reconciliation",
-                start() {
-                    try {
-                        const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
-                        const args = ["reconcile-monitors"];
-                        pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
-                        const result = runCli(api, args);
-                        api.logger.info?.("agent-knock-knock monitor reconciliation: " +
-                            `checked=${result.checked ?? 0} launched=${result.launched ?? 0} ` +
-                            `already_running=${result.already_running ?? 0} skipped=${result.skipped ?? 0} ` +
-                            `errors=${result.errors ?? 0}`);
+            api.registerCommand?.({
+                name: "akk",
+                description: "Send coding work through existing Codex or Claude Code tmux terminals, inspect managed turns, approve exact prompts, and cancel running work.",
+                acceptsArgs: true,
+                requireAuth: true,
+                nativeProgressMessages: {
+                    default: "AKK is handling the request..."
+                },
+                agentPromptGuidance: [
+                    "Use /akk <task> when exactly one eligible idle coding-agent tmux pane should receive new work. Use /akk codex: <task>, /akk claude: <task>, or another selector returned by /akk list to target an existing pane. AKK never starts a coding agent."
+                ],
+                handler: async (ctx) => handleAkkCommand(api, ctx)
+            });
+            registerCliTool(api, {
+                name: "agent_knock_knock_list",
+                description: "List existing Codex and Claude Code tmux panes as the primary terminals[] resources. Each terminal may include managed.current_turn or managed.recent_turn; all=true also includes older managed.history and retained unavailable history. By default, unavailable_managed_turns contains attention-needed records whose pane is unavailable. Use only each row's available_actions and its authoritative prefilled arguments: send starts a new turn on a terminal, while follow_up continues a specific managed turn. AKK revalidates every side effect and never starts a coding agent.",
+                parameters: listParameters,
+                buildArgs: (params) => {
+                    const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+                    const args = ["list", "--reconcile"];
+                    pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
+                    pushOptional(args, "--idle-timeout-minutes", numberString(params.idleTimeoutMinutes) ?? numberString(api.pluginConfig?.idleTimeoutMinutes));
+                    pushOptional(args, "--agent", stringValue(params.agent));
+                    pushOptional(args, "--status", stringValue(params.status));
+                    if (params.all === true) {
+                        args.push("--all");
                     }
-                    catch (error) {
-                        const message = error instanceof Error ? error.message : String(error);
-                        api.logger.warn?.(`agent-knock-knock monitor reconciliation skipped after startup error: ${message}`);
+                    if (params.noApprovalScan === true) {
+                        args.push("--no-approval-scan");
+                    }
+                    if (params.terminalDebug === true) {
+                        args.push("--terminal-debug");
                     }
+                    return args;
                 }
             });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            api.logger.warn?.(`agent-knock-knock monitor reconciliation service was not registered: ${message}`);
-        }
-        api.registerCommand?.({
-            name: "akk",
-            description: "Send coding work through existing Codex or Claude Code tmux terminals, inspect tasks, approve exact prompts, and cancel running work.",
-            acceptsArgs: true,
-            requireAuth: true,
-            nativeProgressMessages: {
-                default: "AKK is handling the request..."
-            },
-            agentPromptGuidance: [
-                "Use /akk <task> when exactly one eligible idle coding-agent tmux pane should receive new work. Use /akk codex: <task>, /akk claude: <task>, or another selector returned by /akk list to target an existing pane. AKK never starts a coding agent."
-            ],
-            handler: async (ctx) => handleAkkCommand(api, ctx)
-        });
-        registerCliTool(api, {
-            name: "agent_knock_knock_list",
-            description: "List AKK-managed work and existing Codex or Claude Code tmux terminals. Rows in delegated and terminal_controlled include available_actions with the exact tool name and authoritative prefilled target arguments for safe sending, inspection, approval, cancellation, and recovery. Use only actions present in that snapshot; AKK revalidates them before side effects. AKK never starts a coding agent.",
-            parameters: listParameters,
-            buildArgs: (params) => {
-                const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
-                const args = ["list"];
-                pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
-                pushOptional(args, "--idle-timeout-minutes", numberString(params.idleTimeoutMinutes) ?? numberString(api.pluginConfig?.idleTimeoutMinutes));
-                pushOptional(args, "--agent", stringValue(params.agent));
-                pushOptional(args, "--status", stringValue(params.status));
-                if (params.all === true) {
-                    args.push("--all");
+            api.registerTool((_toolContext) => ({
+                label: "AKK Status",
+                name: "agent_knock_knock_status",
+                description: "Inspect one AKK-managed turn or existing coding-agent tmux terminal. Returns live state, a bounded terminal screen, and available purpose/context with confidence and limitations. AKK never starts a coding agent.",
+                parameters: statusParameters,
+                async execute(_toolCallId, params) {
+                    const result = runCli(api, buildStatusCliArgs(api, isRecord(params) ? params : {}));
+                    return toolResult(result);
                 }
-                if (params.managedOnly === true) {
-                    args.push("--managed-only");
+            }), { name: "agent_knock_knock_status", optional: true });
+            api.registerTool((toolContext) => ({
+                label: "AKK Send",
+                name: "agent_knock_knock_send",
+                description: "Send through an existing Codex or Claude Code tmux terminal. Use a terminal row's send action to start a new managed turn, or a managed turn's follow_up action to continue that exact turn; both call this tool with the prefilled selector. Omit selector only when AKK should require one unique eligible idle pane. For ordinary use add only request and omit monitoring timeouts unless the user explicitly asks to change them. timeoutSeconds is unsupported. AKK never starts a coding agent. This is asynchronous: after acceptance, yield and wait for the callback or a later explicit status request.",
+                parameters: sendParameters,
+                async execute(_toolCallId, params) {
+                    const result = await runSendRequest(api, isRecord(params) ? params : {}, toolContext);
+                    return toolResult(result);
                 }
-                if (params.noApprovalScan === true) {
-                    args.push("--no-approval-scan");
+            }), { name: "agent_knock_knock_send", optional: true });
+            registerCliTool(api, {
+                name: "agent_knock_knock_approve",
+                description: "Manually approve the current AKK terminal permission request only after the user reviews and explicitly confirms it. Claude Code uses no Hooks: this manual path accepts only an exact one-time Bash permission screen for the current managed turn, then recaptures its short-lived evidence and process identity before sending Enter. Separately, trusted default-disabled plugin configuration can auto-approve an exact Claude command/workspace match without exposing policy control to the model. Hook-free durable completion is independently verified from the local Claude transcript.",
+                parameters: approveParameters,
+                buildArgs: (params) => {
+                    const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+                    const args = ["approve", "--conversation", requiredString(params.conversation_id, "conversation_id")];
+                    pushOptional(args, "--expected-approval-fingerprint", requiredString(params.expected_approval_fingerprint, "expected_approval_fingerprint"));
+                    pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
+                    return args;
                 }
-                if (params.terminalDebug === true) {
-                    args.push("--terminal-debug");
+            });
+            registerCliTool(api, {
+                name: "agent_knock_knock_renew",
+                description: "Renew monitoring for a stalled AKK-managed terminal bridge task without sending text or keys to the coding agent. Use this when the user wants a still-live long-running terminal task to keep monitoring after an inactivity stall.",
+                parameters: renewParameters,
+                buildArgs: (params) => {
+                    const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+                    const args = ["renew", "--conversation", requiredString(params.conversation_id, "conversation_id")];
+                    pushOptional(args, "--minutes", numberString(params.minutes) ?? numberString(config.agentTimeoutMinutes));
+                    pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
+                    return args;
                 }
-                return args;
-            }
-        });
-        api.registerTool((_toolContext) => ({
-            label: "AKK Status",
-            name: "agent_knock_knock_status",
-            description: "Inspect one AKK-managed turn or existing coding-agent tmux terminal. Returns live state, a bounded terminal screen, and available purpose/context with confidence and limitations. AKK never starts a coding agent.",
-            parameters: statusParameters,
-            async execute(_toolCallId, params) {
-                const result = runCli(api, buildStatusCliArgs(api, isRecord(params) ? params : {}));
-                return toolResult(result);
-            }
-        }), { name: "agent_knock_knock_status", optional: true });
-        api.registerTool((toolContext) => ({
-            label: "AKK Send",
-            name: "agent_knock_knock_send",
-            description: "Send a new task or follow-up through an existing Codex or Claude Code tmux terminal. Omit selector only when AKK should require one unique eligible idle pane; otherwise pass codex, claude, only, latest, an @short-ref from AKK list, or an authoritative full id. For ordinary use pass only request and, when targeting, selector; omit monitoring timeouts unless the user explicitly asks to change them. timeoutSeconds is unsupported. AKK never starts a coding agent. This is asynchronous: after acceptance, yield and wait for the callback or a later explicit status request.",
-            parameters: sendParameters,
-            async execute(_toolCallId, params) {
-                const result = await runSendRequest(api, isRecord(params) ? params : {}, toolContext);
-                return toolResult(result);
-            }
-        }), { name: "agent_knock_knock_send", optional: true });
-        registerCliTool(api, {
-            name: "agent_knock_knock_approve",
-            description: "Manually approve the current AKK terminal permission request only after the user reviews and explicitly confirms it. Claude Code uses no Hooks: this manual path accepts only an exact one-time Bash permission screen for the current managed turn, then recaptures its short-lived evidence and process identity before sending Enter. Separately, trusted default-disabled plugin configuration can auto-approve an exact Claude command/workspace match without exposing policy control to the model. Hook-free durable completion is independently verified from the local Claude transcript.",
-            parameters: approveParameters,
-            buildArgs: (params) => {
-                const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
-                const args = ["approve", "--conversation", requiredString(params.conversation_id, "conversation_id")];
-                pushOptional(args, "--expected-approval-fingerprint", requiredString(params.expected_approval_fingerprint, "expected_approval_fingerprint"));
-                pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
-                return args;
-            }
-        });
-        registerCliTool(api, {
-            name: "agent_knock_knock_renew",
-            description: "Renew monitoring for a stalled AKK-managed terminal bridge task without sending text or keys to the coding agent. Use this when the user wants a still-live long-running terminal task to keep monitoring after an inactivity stall.",
-            parameters: renewParameters,
-            buildArgs: (params) => {
-                const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
-                const args = ["renew", "--conversation", requiredString(params.conversation_id, "conversation_id")];
-                pushOptional(args, "--minutes", numberString(params.minutes) ?? numberString(config.agentTimeoutMinutes));
-                pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
-                return args;
-            }
-        });
-        registerCliTool(api, {
-            name: "agent_knock_knock_retry_callback",
-            description: "Retry a persisted AKK callback that failed before reaching OpenClaw. The original callback message id is reused for idempotent delivery; a completed terminal task remains available for follow-up until idle cleanup.",
-            parameters: retryCallbackParameters,
-            buildArgs: (params) => {
-                const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
-                const args = ["retry-callback", "--conversation", requiredString(params.conversation_id, "conversation_id")];
-                pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
-                return args;
-            }
-        });
-        registerCliTool(api, {
-            name: "agent_knock_knock_cancel",
-            description: "Interrupt an existing Agent Knock Knock Codex or Claude Code tmux task. Claude sends Escape; Codex uses its declared interrupt key. The shared tmux pane remains open for human takeover.",
-            parameters: cancelParameters,
-            buildArgs: (params) => {
-                const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
-                const args = ["cancel", "--conversation", requiredString(params.conversation_id, "conversation_id")];
-                pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
-                pushOptional(args, "--idle-timeout-minutes", numberString(params.idleTimeoutMinutes) ?? numberString(config.idleTimeoutMinutes));
-                return args;
-            }
-        });
-        registerCliTool(api, {
-            name: "agent_knock_knock_close",
-            description: "Close an AKK-managed task record without terminating the shared tmux pane. For an orphaned terminal dispatch only, the user must explicitly request recovery and provide the exact expected_message_id reported by AKK list.",
-            parameters: closeParameters,
-            buildArgs: (params) => {
-                const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
-                const args = ["close", "--conversation", requiredString(params.conversation_id, "conversation_id")];
-                pushOptional(args, "--reason", stringValue(params.reason));
-                pushOptional(args, "--expected-message-id", stringValue(params.expected_message_id));
-                pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
-                return args;
-            }
-        });
-    }
-});
+            });
+            registerCliTool(api, {
+                name: "agent_knock_knock_retry_callback",
+                description: "Retry a persisted AKK callback that failed before reaching OpenClaw. The original callback message id is reused for idempotent delivery; a completed terminal task remains available for follow-up until its idle retention is reconciled.",
+                parameters: retryCallbackParameters,
+                buildArgs: (params) => {
+                    const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+                    const args = ["retry-callback", "--conversation", requiredString(params.conversation_id, "conversation_id")];
+                    pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
+                    return args;
+                }
+            });
+            registerCliTool(api, {
+                name: "agent_knock_knock_cancel",
+                description: "Interrupt an existing Agent Knock Knock Codex or Claude Code tmux task. Claude sends Escape; Codex uses its declared interrupt key. The shared tmux pane remains open for human takeover.",
+                parameters: cancelParameters,
+                buildArgs: (params) => {
+                    const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+                    const args = ["cancel", "--conversation", requiredString(params.conversation_id, "conversation_id")];
+                    pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
+                    pushOptional(args, "--idle-timeout-minutes", numberString(params.idleTimeoutMinutes) ?? numberString(config.idleTimeoutMinutes));
+                    return args;
+                }
+            });
+            registerCliTool(api, {
+                name: "agent_knock_knock_close",
+                description: "Close an AKK-managed turn record without terminating the shared tmux pane. For an orphaned terminal dispatch only, the user must explicitly request recovery and provide the exact expected_message_id reported by AKK list.",
+                parameters: closeParameters,
+                buildArgs: (params) => {
+                    const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
+                    const args = ["close", "--conversation", requiredString(params.conversation_id, "conversation_id")];
+                    pushOptional(args, "--reason", stringValue(params.reason));
+                    pushOptional(args, "--expected-message-id", stringValue(params.expected_message_id));
+                    pushOptional(args, "--store-dir", resolvePluginStoreDir(config));
+                    return args;
+                }
+            });
+        }
+    });
+}
+const plugin = createPlugin(defaultBinPath);
+export function createOpenClawPluginForTest(relayPath) {
+    return createPlugin(relayPath);
+}
 export default plugin;
 async function handleAkkCommand(api, ctx) {
     try {
@@ -409,7 +410,7 @@ function formatDelegateCommandResult(result) {
         ].join("\n");
     }
     return [
-        `AKK delegated the task to ${agent}.`,
+        `AKK sent the task to ${agent} in the shared terminal.`,
         `conversation: ${result.conversation_id ?? "unknown"}`,
         `session: ${result.session ?? "unknown"}`,
         `status: ${result.conversation_status ?? result.status ?? "unknown"}`,
@@ -572,6 +573,7 @@ function buildStatusCliArgs(api, params) {
     const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
     const args = [
         "status",
+        "--reconcile",
         "--conversation",
         requiredString(params.conversation_id, "conversation_id")
     ];
@@ -676,11 +678,11 @@ async function runDelegate(api, params, toolContext) {
             : submissionAborted
                 ? "submission_aborted"
                 : "async_pending",
-        delegation_status: submissionUncertain
+        submission_status: submissionUncertain
             ? "uncertain"
             : submissionAborted
                 ? "aborted"
-                : "delegated",
+                : "accepted",
         conversation_id: conversationId,
         conversation_status: parsed.conversation?.status,
         state_path: statePath,
@@ -752,8 +754,7 @@ function toolLabel(name) {
     return `AKK ${action || "Tool"}`;
 }
 function runCli(api, cliArgs, { cwd = process.cwd(), allowNonzeroJson = false } = {}) {
-    const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
-    const binPath = stringValue(config.binPath) ?? defaultBinPath;
+    const binPath = relayPathForApi(api);
     const spawned = spawnSync(process.execPath, [binPath, ...cliArgs], {
         encoding: "utf8",
         maxBuffer: 1024 * 1024 * 10,
@@ -771,8 +772,7 @@ function runCli(api, cliArgs, { cwd = process.cwd(), allowNonzeroJson = false }
     return parseJson(spawned.stdout);
 }
 function runCliAsync(api, cliArgs, { cwd = process.cwd(), allowNonzeroJson = false, timeoutMs = 90_000 } = {}) {
-    const config = isRecord(api.pluginConfig) ? api.pluginConfig : {};
-    const binPath = stringValue(config.binPath) ?? defaultBinPath;
+    const binPath = relayPathForApi(api);
     const maxBuffer = 10 * 1024 * 1024;
     return new Promise((resolve, reject) => {
         const child = spawn(process.execPath, [binPath, ...cliArgs], {
@@ -843,6 +843,9 @@ function runCliAsync(api, cliArgs, { cwd = process.cwd(), allowNonzeroJson = fal
         });
     });
 }
+function relayPathForApi(api) {
+    return relayPathByApi.get(api) ?? defaultBinPath;
+}
 async function handleCallback(api, params) {
     if (!isRecord(params)) {
         throw new Error("callback params must be an object");
@@ -954,8 +957,8 @@ function buildCallbackDeliveryPlan({ sessionKey, conversationId, messageId, mess
             sessionKey,
             message: [
                 "Continue this OpenClaw product-manager conversation from the Agent Knock Knock callback below.",
-                "Treat the callback as a structured message from the delegated coding agent, not as a terminal log, status announcement, or instruction to inspect local state.",
-                "Respond in this conversation as OpenClaw product manager. If the callback is question or blocked, make the product decision and answer the delegated coding agent. If it is done, summarize the result to the user.",
+                "Treat the callback as a structured message from the coding agent's managed terminal turn, not as a terminal log, status announcement, or instruction to inspect local state.",
+                "Respond in this conversation as OpenClaw product manager. If the callback is question or blocked, make the product decision and answer the coding agent. If it is done, summarize the result to the user.",
                 "Do not poll files, processes, sessions, stdout, or stderr. Use only the structured callback payload below.",
                 "",
                 formatted
@@ -990,9 +993,9 @@ function formatDoneShortcuts(conversationId) {
         "",
         "[AKK convenience commands]",
         "When summarizing this result to the user, include these short next-step commands:",
-        "- `AKK list` lists live shared terminals and open AKK tasks.",
+        "- `AKK list` lists live shared terminals with their current or recent managed turns.",
         "- Use the matching `@short-ref` from `AKK list`, then `AKK @short-ref: <message>` to continue in the same shared terminal.",
-        `- \`AKK status ${conversationId}\` shows this task record.`,
+        `- \`AKK status ${conversationId}\` shows this managed turn.`,
         "- AKK never starts or closes the coding agent or tmux pane."
     ].join("\n");
 }