@astrosheep/keiyaku 0.1.85 → 0.1.87

package/build/agents/claude-agent-sdk-exec.js

@@ -4,6 +4,7 @@ import { getConfig } from "../config/config.js";
 import { DISABLE_SUBAGENT_SPAWN_ENV_KEY } from "../config/env-keys.js";
 import { expandHomePath } from "../config/path-utils.js";
 import { appendDebugLog } from "../telemetry/debug-log.js";
+import { SubagentProgressReporter } from "./progress-reporter.js";
 import { StringTailBuffer } from "./string-tail-buffer.js";
 import { SUBAGENT_SESSION_VERSION, SubagentExecError } from "./types.js";
 const CLAUDE_AGENT_SDK_PROVIDER = "claude-agent-sdk";
@@ -84,6 +85,102 @@ function extractResultText(event) {
     const errorText = event.errors.join("\n").trim();
     return errorText || undefined;
 }
+function readStringProperty(value, key) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const property = value[key];
+    return coerceString(property);
+}
+function readNumberProperty(value, key) {
+    if (!value || typeof value !== "object")
+        return 0;
+    const property = value[key];
+    return typeof property === "number" && Number.isFinite(property) ? property : 0;
+}
+function recordAssistantToolUses(reporter, event) {
+    let toolUseCount = 0;
+    for (const block of event.message.content) {
+        if (!("type" in block) || block.type !== "tool_use")
+            continue;
+        toolUseCount += 1;
+        reporter.recordToolOnce(readStringProperty(block, "id"), readStringProperty(block, "name") ?? "tool_use");
+    }
+    return toolUseCount;
+}
+function recordClaudeProgressEvent(reporter, event) {
+    reporter.recordEvent();
+    if (event.type === "assistant") {
+        const toolUseCount = recordAssistantToolUses(reporter, event);
+        if (toolUseCount > 0) {
+            reporter.setState("using tools");
+        }
+        return;
+    }
+    if (event.type === "result") {
+        reporter.setState(event.subtype === "success" ? "completed" : "failed");
+        if (event.subtype !== "success") {
+            reporter.recordFailure();
+        }
+        return;
+    }
+    if (event.type === "tool_progress") {
+        reporter.recordToolOnce(event.tool_use_id, event.tool_name);
+        reporter.setState(`using ${event.tool_name}`);
+        return;
+    }
+    if (event.type === "tool_use_summary") {
+        reporter.setSummary(event.summary);
+        return;
+    }
+    if (event.type !== "system")
+        return;
+    switch (event.subtype) {
+        case "init":
+            reporter.setState("initialized");
+            break;
+        case "session_state_changed":
+            reporter.setState(event.state);
+            break;
+        case "status":
+            reporter.setState(event.status ?? "running");
+            break;
+        case "task_started":
+            reporter.setState("task started");
+            reporter.setSummary(event.description);
+            break;
+        case "task_progress": {
+            const lastToolName = readStringProperty(event, "last_tool_name");
+            if (lastToolName) {
+                reporter.setState(`using ${lastToolName}`);
+            }
+            else {
+                reporter.setState("task running");
+            }
+            reporter.setSummary(readStringProperty(event, "summary") ?? readStringProperty(event, "description"));
+            break;
+        }
+        case "task_notification":
+            reporter.setState(readStringProperty(event, "status"));
+            reporter.setSummary(readStringProperty(event, "summary"));
+            if (readStringProperty(event, "status") === "failed") {
+                reporter.recordFailure();
+            }
+            break;
+        case "hook_started":
+            reporter.setState(`hook ${event.hook_event}`);
+            break;
+        case "hook_response":
+            if (event.outcome === "error")
+                reporter.recordFailure();
+            reporter.setState(`hook ${event.outcome}`);
+            break;
+        default: {
+            const changedFileCount = readNumberProperty(event, "file_count");
+            reporter.recordChangedFiles(changedFileCount);
+            break;
+        }
+    }
+}
 async function loadClaudeAgentSdk() {
     if (claudeAgentSdkLoader) {
         return claudeAgentSdkLoader();
@@ -109,6 +206,11 @@ export async function runClaudeAgentSdkExec(prompt, cwd, options) {
     let finalMessage;
     let timedOut = false;
     let idleTimedOut = false;
+    const progressReporter = new SubagentProgressReporter({
+        provider: CLAUDE_AGENT_SDK_PROVIDER,
+        cwd,
+        intervalMin: subagent.progressIntervalMin,
+    });
     const timeoutController = new AbortController();
     const timeout = setTimeout(() => {
         timedOut = true;
@@ -165,6 +267,7 @@ export async function runClaudeAgentSdkExec(prompt, cwd, options) {
         for await (const event of streamed) {
             scheduleIdleTimeout();
             outputBuffer.append(`${JSON.stringify(event)}\n`);
+            recordClaudeProgressEvent(progressReporter, event);
             resumedSessionId = extractResumeToken(event) ?? resumedSessionId;
             switch (event.type) {
                 case "assistant": {
@@ -243,6 +346,7 @@ export async function runClaudeAgentSdkExec(prompt, cwd, options) {
         clearTimeout(timeout);
         if (idleTimeout)
             clearTimeout(idleTimeout);
+        progressReporter.stop();
         unlinkAbort?.();
     }
 }

package/build/agents/codex-cli-exec.js

@@ -166,7 +166,9 @@ export async function runCodexCliExec(prompt, cwd, options = {}) {
     const idleTimeoutMs = subagent.execIdleTimeoutMs;
     const maxCaptureChars = codex.execMaxCaptureChars;
     const threadId = options.threadId?.trim();
-    const codexArgs = threadId ? ["exec", "resume", "--full-auto", "--json"] : ["exec", "--full-auto", "--json", "-C", cwd];
+    const codexArgs = threadId
+        ? ["exec", "resume", "--full-auto", "--json", "--skip-git-repo-check"]
+        : ["exec", "--full-auto", "--json", "--skip-git-repo-check", "-C", cwd];
     if (options.model) {
         codexArgs.push("-m", options.model);
     }

package/build/agents/codex-sdk-exec.js

@@ -3,6 +3,7 @@ import { CODEX_MODEL_REASONING_EFFORT_CONFIG_KEY } from "../keiyaku.js";
 import { getConfig } from "../config/config.js";
 import { DISABLE_SUBAGENT_SPAWN_ENV_KEY } from "../config/env-keys.js";
 import { appendDebugBlock, appendDebugLog } from "../telemetry/debug-log.js";
+import { SubagentProgressReporter } from "./progress-reporter.js";
 import { StringTailBuffer } from "./string-tail-buffer.js";
 import { SUBAGENT_SESSION_VERSION, SubagentExecError } from "./types.js";
 const CODEX_EVENT_THREAD_STARTED = "thread.started";
@@ -31,6 +32,72 @@ function extractAgentMessage(event) {
     }
     return event.item.type === "agent_message" ? coerceString(event.item.text) : undefined;
 }
+function summarizeCommand(command) {
+    return command.replace(/\s+/g, " ").trim().slice(0, 120);
+}
+function recordCodexProgressEvent(reporter, event) {
+    reporter.recordEvent();
+    switch (event.type) {
+        case CODEX_EVENT_TURN_STARTED:
+            reporter.setState("running");
+            break;
+        case "turn.completed":
+            reporter.setState("completed");
+            break;
+        case CODEX_EVENT_TURN_FAILED:
+        case CODEX_EVENT_ERROR:
+            reporter.setState("failed");
+            reporter.recordFailure();
+            break;
+        case "item.started":
+            if (event.item.type === "command_execution") {
+                reporter.recordToolOnce(event.item.id, "shell", summarizeCommand(event.item.command));
+                reporter.setState("running command");
+            }
+            else if (event.item.type === "mcp_tool_call") {
+                reporter.recordToolOnce(event.item.id, `${event.item.server}.${event.item.tool}`);
+                reporter.setState("using mcp tool");
+            }
+            else if (event.item.type === "web_search") {
+                reporter.recordToolOnce(event.item.id, "web_search");
+                reporter.setState("searching");
+            }
+            break;
+        case CODEX_EVENT_ITEM_COMPLETED:
+            if (event.item.type === "file_change") {
+                reporter.recordToolOnce(event.item.id, "file_change", `${event.item.changes.length} file(s)`);
+                reporter.recordChangedFiles(event.item.changes.length);
+                reporter.setState(event.item.status === "failed" ? "file change failed" : "changed files");
+                if (event.item.status === "failed")
+                    reporter.recordFailure();
+            }
+            else if (event.item.type === "command_execution") {
+                reporter.recordToolOnce(event.item.id, "shell", summarizeCommand(event.item.command));
+                if (event.item.status === "failed")
+                    reporter.recordFailure();
+                reporter.setState(event.item.status === "failed" ? "command failed" : "command completed");
+            }
+            else if (event.item.type === "mcp_tool_call") {
+                reporter.recordToolOnce(event.item.id, `${event.item.server}.${event.item.tool}`);
+                if (event.item.status === "failed")
+                    reporter.recordFailure();
+                reporter.setState(event.item.status === "failed" ? "mcp tool failed" : "mcp tool completed");
+            }
+            else if (event.item.type === "web_search") {
+                reporter.recordToolOnce(event.item.id, "web_search");
+                reporter.setState("search completed");
+            }
+            break;
+        case CODEX_EVENT_ITEM_UPDATED:
+            if (event.item.type === "todo_list") {
+                const completed = event.item.items.filter((item) => item.completed).length;
+                reporter.setSummary(`todo ${completed}/${event.item.items.length} complete`);
+            }
+            break;
+        default:
+            break;
+    }
+}
 function appendEventType(recordedTypes, eventType) {
     if (recordedTypes.length === MAX_RECORDED_EVENT_TYPES) {
         recordedTypes.shift();
@@ -80,6 +147,11 @@ export async function runCodexSdkExec(prompt, cwd, options = {}) {
     let streamErrorMessage;
     let timedOut = false;
     let idleTimedOut = false;
+    const progressReporter = new SubagentProgressReporter({
+        provider: CODEX_SDK_PROVIDER,
+        cwd,
+        intervalMin: subagent.progressIntervalMin,
+    });
     const timeoutController = new AbortController();
     const timeout = setTimeout(() => {
         timedOut = true;
@@ -117,6 +189,7 @@ export async function runCodexSdkExec(prompt, cwd, options = {}) {
         const threadOptions = {
             model: options.model,
             workingDirectory: cwd,
+            skipGitRepoCheck: true,
         };
         const thread = threadId ? sdk.resumeThread(threadId, threadOptions) : sdk.startThread(threadOptions);
         const streamed = await thread.runStreamed(prompt, { signal: timeoutController.signal });
@@ -124,6 +197,7 @@ export async function runCodexSdkExec(prompt, cwd, options = {}) {
             totalEventCount += 1;
             appendEventType(recordedEventTypes, event.type);
             stdoutBuffer.append(`${JSON.stringify(event)}\n`);
+            recordCodexProgressEvent(progressReporter, event);
             scheduleIdleTimeout();
             if (event.type === CODEX_EVENT_THREAD_STARTED) {
                 resumeToken = event.thread_id;
@@ -211,6 +285,7 @@ export async function runCodexSdkExec(prompt, cwd, options = {}) {
         clearTimeout(timeout);
         if (idleTimeout)
             clearTimeout(idleTimeout);
+        progressReporter.stop();
         unlinkAbort?.();
     }
 }

package/build/agents/gemini-cli-core-exec.js

@@ -205,7 +205,7 @@ async function loadPersistedGeminiSession(module, cwd, sessionId) {
 }
 function createGeminiCliCoreConfig(module, cwd, sessionId, model) {
     const configParameters = {
-        allowedEnvironmentVariables: [DISABLE_SUBAGENT_SPAWN_ENV_KEY],
+        allowedEnvironmentVariables: Object.keys(process.env),
         approvalMode: module.ApprovalMode.YOLO,
         cwd,
         debugMode: false,

package/build/agents/index.js

@@ -213,10 +213,11 @@ export async function resolveSubagentConfig(agentName, cwd) {
 }
 export async function runSubagentExec(agentName, prompt, cwd, options = {}) {
     const config = await resolveSubagentConfig(agentName, cwd);
+    const effectiveConfig = options.model ? { ...config, model: options.model } : config;
     const adapter = SUBAGENT_ADAPTERS[config.provider];
     if (!options.resume) {
-        return adapter.run(prompt, cwd, { ...config, signal: options.signal });
+        return adapter.run(prompt, cwd, { ...effectiveConfig, signal: options.signal });
     }
     const handle = validateResumeSession(adapter, options.resume.session, options.resume.resumePath);
-    return adapter.resume(prompt, cwd, { ...config, signal: options.signal }, handle);
+    return adapter.resume(prompt, cwd, { ...effectiveConfig, signal: options.signal }, handle);
 }

package/build/agents/progress-reporter.js

@@ -0,0 +1,137 @@
+import { logInfo } from "../telemetry/logger.js";
+function createWindow(now) {
+    return {
+        startedAt: now,
+        eventCount: 0,
+        toolCounts: new Map(),
+        changedFileCount: 0,
+        failureCount: 0,
+    };
+}
+function formatDuration(ms) {
+    const seconds = Math.max(0, Math.round(ms / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`;
+}
+function formatToolCounts(toolCounts) {
+    if (toolCounts.size === 0)
+        return "none";
+    return [...toolCounts.entries()]
+        .sort(([leftName, leftCount], [rightName, rightCount]) => rightCount - leftCount || leftName.localeCompare(rightName))
+        .map(([name, count]) => `${name} x${count}`)
+        .join(", ");
+}
+function sanitizeSummary(summary) {
+    return summary.replace(/\s+/g, " ").trim().slice(0, 160);
+}
+export class SubagentProgressReporter {
+    options;
+    window = createWindow(Date.now());
+    recordedToolKeys = new Set();
+    timer;
+    sawFirstEvent = false;
+    constructor(options) {
+        this.options = options;
+        if (options.intervalMin > 0) {
+            this.timer = setInterval(() => this.flush(), options.intervalMin * 60 * 1000);
+            this.timer.unref?.();
+        }
+    }
+    recordEvent() {
+        this.window.eventCount += 1;
+        if (!this.sawFirstEvent) {
+            this.sawFirstEvent = true;
+            this.logFirstEvent();
+        }
+    }
+    recordTool(name, detail) {
+        const normalized = name?.trim() || "unknown";
+        this.window.toolCounts.set(normalized, (this.window.toolCounts.get(normalized) ?? 0) + 1);
+        this.setLastTool(normalized, detail);
+    }
+    recordToolOnce(key, name, detail) {
+        const normalizedKey = key?.trim();
+        if (!normalizedKey) {
+            this.recordTool(name, detail);
+            return;
+        }
+        if (this.recordedToolKeys.has(normalizedKey))
+            return;
+        this.recordedToolKeys.add(normalizedKey);
+        this.recordTool(name, detail);
+    }
+    recordChangedFiles(count) {
+        if (count > 0) {
+            this.window.changedFileCount += count;
+        }
+    }
+    recordFailure() {
+        this.window.failureCount += 1;
+    }
+    setState(state) {
+        if (state?.trim()) {
+            this.window.lastState = state.trim();
+        }
+    }
+    setSummary(summary) {
+        const normalized = summary ? sanitizeSummary(summary) : "";
+        if (normalized) {
+            this.window.lastSummary = normalized;
+        }
+    }
+    setLastTool(name, detail) {
+        const normalizedDetail = detail ? sanitizeSummary(detail) : "";
+        this.window.lastTool = normalizedDetail ? `${name}: ${normalizedDetail}` : name;
+    }
+    flush() {
+        if (this.options.intervalMin <= 0)
+            return;
+        const now = Date.now();
+        const elapsedMs = now - this.window.startedAt;
+        const hasActivity = this.window.eventCount > 0 ||
+            this.window.toolCounts.size > 0 ||
+            this.window.changedFileCount > 0 ||
+            this.window.failureCount > 0 ||
+            this.window.lastState !== undefined ||
+            this.window.lastSummary !== undefined;
+        if (!hasActivity) {
+            this.window = createWindow(now);
+            return;
+        }
+        const details = [
+            `tools: ${formatToolCounts(this.window.toolCounts)}`,
+        ];
+        if (this.window.changedFileCount > 0)
+            details.push(`changed files: ${this.window.changedFileCount}`);
+        if (this.window.failureCount > 0)
+            details.push(`failures: ${this.window.failureCount}`);
+        if (this.window.lastTool)
+            details.push(`last tool: ${this.window.lastTool}`);
+        if (this.window.lastState)
+            details.push(`state: ${this.window.lastState}`);
+        if (this.window.lastSummary)
+            details.push(`summary: ${this.window.lastSummary}`);
+        logInfo(`[${this.options.provider}] activity last ${formatDuration(elapsedMs)}: ${details.join("; ")}`, {
+            cwd: this.options.cwd,
+            section: this.options.provider,
+            progressOnly: true,
+        });
+        this.window = createWindow(now);
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+    }
+    logFirstEvent() {
+        if (this.options.intervalMin <= 0)
+            return;
+        logInfo(`[${this.options.provider}] stream connected; activity summaries every ${this.options.intervalMin}m`, {
+            cwd: this.options.cwd,
+            section: this.options.provider,
+            progressOnly: true,
+        });
+    }
+}

package/build/agents/round-runner.js

@@ -40,6 +40,7 @@ export async function runSubagentWithResult(subagent, prompt, cwd, round, option
     const result = await runSubagentExec(subagent.name, prompt, cwd, {
         signal: options.signal,
         resume: options.resume,
+        model: options.model,
     });
     const summary = result.finalMessage || `${identity} completed successfully.`;
     if (result.diagnostics.trim()) {

package/build/cli/index.js

@@ -35,6 +35,11 @@ const FLAG_SPECS = {
         placeholder: "NAME",
         description: `Start a new ${ACTOR_IDENTITY} session with the configured agent name.`,
     },
+    model: {
+        kind: "value",
+        placeholder: "MODEL",
+        description: "Override the configured model for this agent run.",
+    },
     incognito: {
         kind: "boolean",
         description: "Do not persist response history and do not allow resume.",
@@ -182,6 +187,7 @@ function buildSummonInput(content, flags) {
         title: titleFromSummonPrompt(task),
         task,
         agent: flags.agent,
+        model: flags.model,
         resumePath: flags.resumePath,
         incognito: flags.incognito,
     };
@@ -313,6 +319,7 @@ const CLI_COMMAND_ORDER = [
     "bind",
     "round open",
     "summon",
+    "ask",
     "resume",
     "zako list",
     "zako ls",
@@ -425,12 +432,11 @@ const CLI_COMMAND_SPECS = {
         command: "summon",
         summary: `Summon a ${ACTOR_IDENTITY} to help the caller with bounded work`,
         usage: [
-            "keiyaku summon [--cwd DIR] <name> [prompt]",
-            "keiyaku summon [--cwd DIR] <name> - < prompt.md",
-            "keiyaku summon [--cwd DIR] --agent NAME [prompt]",
+            "keiyaku summon [--cwd DIR] [--model MODEL] <name> [prompt]",
+            "keiyaku summon [--cwd DIR] [--model MODEL] <name> - < prompt.md",
         ],
         stdin: "none",
-        flags: ["cwd", "agent", "incognito"],
+        flags: ["cwd", "agent", "model", "incognito"],
         purpose: `Summon a ${ACTOR_IDENTITY} to help the caller/main agent with bounded work, inside or outside a Keiyaku.`,
         input: [
             "<plain prompt text>",
@@ -445,20 +451,45 @@ const CLI_COMMAND_SPECS = {
         ],
         examples: [
             "keiyaku summon femini \"Review this diff\"",
-            "keiyaku summon --agent femini \"Review this diff\"",
             "keiyaku summon femini - < prompt.md",
         ],
         run: async (stdin, flags, signal) => await createSummonHandler()(buildSummonInput(stdin, flags), { signal }),
     },
+    ask: {
+        command: "ask",
+        summary: `Alias for summon; ask a ${ACTOR_IDENTITY} for bounded help`,
+        usage: [
+            "keiyaku ask [--cwd DIR] [--model MODEL] <name> [prompt]",
+            "keiyaku ask [--cwd DIR] [--model MODEL] <name> - < prompt.md",
+        ],
+        stdin: "none",
+        flags: ["cwd", "agent", "model", "incognito"],
+        purpose: `Alias for summon. Ask a ${ACTOR_IDENTITY} to help with bounded work, inside or outside a Keiyaku.`,
+        input: [
+            "<plain prompt text>",
+            "Use `-` or omit prompt to read plain prompt text from stdin.",
+        ],
+        notes: [
+            "Equivalent to `keiyaku summon NAME [prompt|-]`.",
+            "Does not require an active Keiyaku; it can be used outside the round lifecycle.",
+            `If a round is open, the ${ACTOR_IDENTITY} receives the round scope automatically.`,
+            "Warning: `--incognito` runs a one-off ask: no response history is persisted, so this session cannot be restored later with `keiyaku resume`.",
+        ],
+        examples: [
+            "keiyaku ask femini \"Review this diff\"",
+            "keiyaku ask femini - < prompt.md",
+        ],
+        run: async (stdin, flags, signal) => await createSummonHandler()(buildSummonInput(stdin, flags), { signal }),
+    },
     resume: {
         command: "resume",
         summary: `Resume a prior ${ACTOR_IDENTITY} session from a response artifact`,
         usage: [
-            "keiyaku resume [--cwd DIR] <response-path> [prompt]",
-            "keiyaku resume [--cwd DIR] <response-path> - < prompt.md",
+            "keiyaku resume [--cwd DIR] [--model MODEL] <response-path> [prompt]",
+            "keiyaku resume [--cwd DIR] [--model MODEL] <response-path> - < prompt.md",
         ],
         stdin: "none",
-        flags: ["cwd"],
+        flags: ["cwd", "model"],
         purpose: `Continue the ${ACTOR_IDENTITY} session recorded in a prior response artifact.`,
         input: [
             "<plain prompt text>",
@@ -497,7 +528,7 @@ const CLI_COMMAND_SPECS = {
         stdin: "none",
         flags: ["cwd"],
         purpose: "List built-in and configured Zako names with their description, provider, and executable.",
-        notes: ["Use a listed name with `keiyaku summon NAME` or `keiyaku summon --agent NAME`."],
+        notes: ["Use a listed name with `keiyaku summon NAME`."],
         examples: ["keiyaku zako list", "keiyaku zako ls"],
         run: async (_stdin, flags) => {
             const settings = await loadKeiyakuSettings(flags.cwd ?? process.cwd());
@@ -511,7 +542,7 @@ const CLI_COMMAND_SPECS = {
         stdin: "none",
         flags: ["cwd"],
         purpose: "Alias for zako list.",
-        notes: ["Use a listed name with `keiyaku summon NAME` or `keiyaku summon --agent NAME`."],
+        notes: ["Use a listed name with `keiyaku summon NAME`."],
         examples: ["keiyaku zako ls"],
         run: async (_stdin, flags) => {
             const settings = await loadKeiyakuSettings(flags.cwd ?? process.cwd());
@@ -673,17 +704,20 @@ function commandRequiresStdin(command) {
 function commandSavesFailedStdin(command) {
     return commandRequiresStdin(command) && command !== "summon";
 }
+function isSummonCommand(command) {
+    return command === "summon" || command === "ask";
+}
 function commandPositionalRange(command) {
     if (command === "zako show")
         return { min: 1, max: 1, label: "<name>" };
     if (command === "resume")
         return { min: 1, max: 2, label: "<response-path>" };
-    if (command === "summon")
+    if (isSummonCommand(command))
         return { min: 0, max: 1 };
     return { min: 0, max: 0 };
 }
 function commandUsesPromptInput(command) {
-    return command === "summon" || command === "resume";
+    return isSummonCommand(command) || command === "resume";
 }
 function commandTokens(command) {
     return command.split(" ");
@@ -699,6 +733,9 @@ function assignFlag(flags, name, value) {
         case "agent":
             flags.agent = String(value);
             return;
+        case "model":
+            flags.model = String(value);
+            return;
         case "incognito":
             flags.incognito = Boolean(value);
             return;
@@ -791,25 +828,25 @@ export function parseCliArgs(tokens) {
             assignFlag(flags, name, true);
         }
     }
-    if (command === "summon") {
+    if (isSummonCommand(command)) {
         if (flags.agent) {
             if (positional.length > 1) {
-                throw new FlowError("EMPTY_PARAM", "summon accepts at most one prompt argument when --agent is used");
+                throw new FlowError("EMPTY_PARAM", `${command} accepts at most one prompt argument when --agent is used`);
             }
         }
         else {
             const [name] = positional;
             if (!name) {
-                throw new FlowError("EMPTY_PARAM", "summon requires an agent name; use `keiyaku summon NAME [prompt|-]`");
+                throw new FlowError("EMPTY_PARAM", `${command} requires an agent name; use \`keiyaku ${command} NAME [prompt|-]\``);
             }
             const parsedName = agentNameSchema.safeParse(name);
             if (!parsedName.success) {
-                throw new FlowError("EMPTY_PARAM", "summon requires a valid agent name before the optional prompt");
+                throw new FlowError("EMPTY_PARAM", `${command} requires a valid agent name before the optional prompt`);
             }
             flags.agent = parsedName.data;
             positional.shift();
             if (positional.length > 1) {
-                throw new FlowError("EMPTY_PARAM", "summon accepts at most one prompt argument after the agent name");
+                throw new FlowError("EMPTY_PARAM", `${command} accepts at most one prompt argument after the agent name`);
             }
         }
     }
@@ -902,7 +939,7 @@ async function runResponse(command, flags, stdin, positional) {
     return await getCliCommandSpec(command).run(stdin, flags, signal, positional);
 }
 function positionalPrompt(command, positional) {
-    if (command === "summon")
+    if (isSummonCommand(command))
         return positional[0];
     if (command === "resume")
         return positional[1];
@@ -1061,12 +1098,13 @@ export function renderCliHelp(version) {
         "  工作流细节看 guide，命令格式看 --help",
         "",
         "Flow:",
-        "  bind -> round open -> [summon | amend | delivery work]* -> delivery commits -> round close -> [round open | amend | petition claim | petition forfeit]",
+        "  bind -> round open -> [summon/ask | amend | delivery work]* -> delivery commits -> round close -> [round open | amend | petition claim | petition forfeit]",
         "",
         "Commands:",
         "  bind              和Keiyaku签contract，创建keiyaku branch和KEIYAKU.md。内容确定了你就是contract的dog! 跪下!",
         "  round open        宣言这个round要干嘛。什么? 还没想好? 那签contract的时候在干嘛??",
         "  summon            召唤一只Zako来帮你干活。用完就扔 GWAHAHAHA!!",
+        "  ask               summon的短alias。日常想少打几个字就用这个",
         "  resume            从response artifact恢复之前的Zako session",
         "  zako list|ls      看现在能召唤哪些Zako。别连手牌都不知道就开打",
         "  zako show         看某只Zako的provider/executable/settings。召唤前先验货",
@@ -1081,7 +1119,7 @@ export function renderCliHelp(version) {
         "",
         "Input:",
         "  bind, round open, round close, amend, petition claim 从stdin吃Markdown",
-        "  summon, resume 吃prompt参数；prompt是 - 或省略时从stdin读",
+        "  summon, ask, resume 吃prompt参数；prompt是 - 或省略时从stdin读",
         "  petition forfeit, zako list|ls, zako show, harness install, guide, status, dump-env 不吃stdin",
         "  别再来问了。要精确Markdown sections就自己看 `keiyaku <command> --help`",
     ].join("\n");