maka-agent 0.2.1-dev.91.20261018 → 0.2.2-dev.92.20261019

package/DISCLAIMER-WIP

@@ -12,7 +12,7 @@ conditions. What follows is a list of issues the project is currently aware of
 (this list is likely to be incomplete):
 
  * The initial-code authorization review remains open at
-   https://github.com/apache/maka/issues/3268. Since RC1, the ASF has recorded
+   https://github.com/apache/maka/issues/3268. Since 0.2.0 RC1, the ASF has recorded
    the ICLA of contributor Mingqwqqaq, and the Deep Research implementation
    has been removed. The review still needs to record the authorization basis
    for the retained initial code; these changes do not establish that an SGA

package/LICENSE

@@ -218,7 +218,9 @@ License: Apache-2.0
 These patches modify the execution time policy and its SDK forwarding. The
 Apache License, Version 2.0 above applies. The generated run Worker includes
 embedded third-party code; its upstream notices and license texts are retained
-in patches/run-2.1.4-notices.md.
+in patches/run-2.1.4-notices.md. The patch carries no WebAssembly binary:
+postinstall substitutes the unchanged payload from the installed run package
+for `__MAKA_RUN_WASM_BASE64__` before applying the patch.
 
 Vercel AI SDK
 
@@ -240,7 +242,7 @@ License, Version 2.0 above applies to the adapted material.
 The pinned versions are the ones present when the adaptation was made. The
 adapted declarations are unchanged through @ai-sdk/provider-utils 5.0.25 and
 @ai-sdk/provider 4.0.7, the versions recorded by the code origin audit. Maka
-also redistributes a patch against @ai-sdk/provider-utils 5.0.40; that patch
+also redistributes a patch against @ai-sdk/provider-utils 5.0.51; that patch
 modifies Apache-2.0 source and is covered by the license reproduced above.
 
 Astryx
@@ -622,6 +624,9 @@ License: MIT
 adaptations of this component.
 The following MIT License applies to that material:
 
+Maka-authored modifications are licensed under the Apache License, Version 2.0
+reproduced above; the upstream portions retain the MIT terms below.
+
 MIT License
 
 Copyright (c) 2025 Cua AI, Inc.
@@ -809,8 +814,7 @@ Desktop renderer vendored source assets
 
 The source archive includes third-party SVG paths and source assets from
 Lobe Icons (MIT), LocalAI (MIT), Simple Icons (CC0-1.0), TDesign Icons (MIT),
-MingCute (Apache-2.0), Allogo (MIT), Ant Design Icons (MIT), and Semi Design
-(MIT), used by the desktop renderer. Their file-by-file inventory, immutable upstream revisions,
+MingCute (Apache-2.0), and Allogo (MIT), used by the desktop renderer. Their file-by-file inventory, immutable upstream revisions,
 copyright notices, and license texts are in:
 
   apps/desktop/src/renderer/public/THIRD_PARTY_LICENSES.txt

package/README.md

@@ -48,7 +48,7 @@ conditions. What follows is a list of issues the project is currently aware of
 (this list is likely to be incomplete):
 
  * The initial-code authorization review remains open at
-   https://github.com/apache/maka/issues/3268. Since RC1, the ASF has recorded
+   https://github.com/apache/maka/issues/3268. Since 0.2.0 RC1, the ASF has recorded
    the ICLA of contributor Mingqwqqaq, and the Deep Research implementation
    has been removed. The review still needs to record the authorization basis
    for the retained initial code; these changes do not establish that an SGA
@@ -142,6 +142,118 @@ Maka asks before privileged tool operations by default. `maka run --yolo` grants
 and network access and should only be used in an environment you are prepared to let the task
 modify.
 
+
+For another agent to drive a Session, request structured output or explicitly submit without waiting:
+
+```sh
+maka run "Inspect this project" --json
+maka run "Inspect this project" --no-wait
+```
+
+Both forms return a `sessionId` in their JSON result. Ordinary runs still wait and print the final
+answer by default. Built-in AskUser is an exception: it returns question JSON and exits 0
+while the Turn waits. Scripts that need a final answer should use `--json` and inspect `status`,
+not treat exit code 0 alone as task completion. `--no-wait` returns after admission; use the
+Session ID to observe the eventual result. Given a returned Session ID in `$session`:
+
+```sh
+maka run --session "$session" --status
+maka run --session "$session" --wait --json
+maka run --session "$session" --answer '["Yes",null]' --wait --json
+maka run --session "$session" "Inspect the tests next" --queue --wait --json
+maka run --session "$session" "Focus on the parser" --steer --no-wait
+maka run --session "$session" --result --json
+maka run --session "$session" --resume --wait --json
+```
+
+Session controls (`--session`) inherit the Host's saved permissions, just as they inherit the
+model and working directory. Continuing, queueing, steering, or answering does not require another
+`--yolo` and does not change the boundary. Add `--yolo` only to explicitly grant full access.
+`--status` reports `executionBoundary`: managed `read_only`/`writable`, bypass, or external.
+A read-only task instruction does not turn a bypass Session into an enforced read-only Session.
+The legacy blocking `--resume <id>` selector retains its explicit `--yolo` requirement for bypass.
+
+An ordinary built-in AskUser returns `needs_input`, the questions and options, with exit code 0.
+The Host retains the waiting Turn. `--answer` accepts one string or `null` per question in a JSON
+array and continues the original tool call and Turn. It does not need `--resume`. A failed or
+uncertain answer submission is not automatically retried; read the current questions before
+choosing what to do next. Multiple pending batches are reported, and an answer is refused when
+the current batch cannot be selected uniquely.
+
+For Host-owned Session execution, `--wait` and `--status` return `needs_approval` with
+`approvalRequests` when a sandbox expansion is pending. Each entry contains its `kind`, requested
+`expansion`, and `justification`; internal request IDs stay inside the CLI. Review the scope, then:
+
+```sh
+maka run --session "$session" --approve --wait --json
+maka run --session "$session" --deny --wait --json
+```
+
+These are alternative decisions, not a sequence to execute. Both continue the original Turn and
+require exactly one pending sandbox request in the Session; none or multiple are rejected without
+submitting a decision. They do not need `--yolo` and cannot be combined with it. Approval applies
+the requested expansion through the Host's managed boundary; it does not change the Session to
+bypass. The expanded boundary is saved for subsequent execution in the Session. The flags
+target the request pending when that CLI invocation attaches. Do not automatically
+retry a decision after an uncertain result: read the current requests before deciding again.
+Ordinary blocking runs retain their existing sandbox-boundary denial behavior.
+
+For coordination, submit follow-ups without blocking, then service the Session's interactions:
+
+```sh
+maka run --session "$session" "Inspect the tests next" --queue --no-wait --json
+maka run --session "$session" --wait --json
+```
+
+Worker admission receipts have `submission: "started"`, `"queued"`, or `"steering"`. Their `status`
+describes the currently observed Session, not completion of the submitted message. A queued receipt
+can include `needs_input` and the current Turn's questions, or `needs_approval` and its sandbox
+request. Answer that interaction before expecting the follow-up to execute. `queued` is the
+observed total of follow-up and steering messages; it is not an exact position. An admission
+receipt omits this count until its queue projection has caught up; use status for a fresh view. Status also reports
+`providerRetry` when the Host has published a retry, without guessing activity from silence.
+
+Assistant Inbox conversations instead return `submission: "inbox"`, without a worker result or queue count, even with `--wait`. This confirms Inbox admission only; inspect delegated work through its own worker Session.
+
+Queue is the default: each explicit queued message opens its own subsequent Turn. Steer uses the
+Host's existing current-Turn delivery and may carry over if it misses that Turn's last boundary.
+Submitting a queued prompt with `--wait` follows that message's execution. It does not return
+questions from an earlier Turn blocking the queue; service those through a separate Session
+wait/answer call, or use the coordination workflow above. Steer with `--wait`
+observes the Turn selected on attachment; it does not guarantee consumption before that Turn ends. A standalone `--wait` fixes its
+target on attachment; when idle, it reads the latest result. `--result` never waits for an active
+Turn. Status and result queries do not prepare a model or start MCP. Interrupting Session
+observation with Ctrl+C leaves Host execution running; legacy blocking run cancellation retains
+its existing behavior. To stop Host execution explicitly, use `maka run --session "$session" --stop --json`.
+Stop targets the current Turn observed on attachment and needs no `--yolo`; a successful request
+exits 0. A successful explicit or implicit status query also exits 0 even if it reports a failed
+or cancelled Turn; result/wait retain the task's failure exit code. Stop and status are not
+assertions that the assigned task succeeded.
+
+Permission requests, MCP forms, and other interactions that this Session CLI cannot answer
+remain waiting in the Host. A wait reports the actual interaction kind and a recovery command: use an
+interactive client on the same Host, or stop the Turn explicitly. Detached admission does not
+promise that subsequent execution will need no interaction.
+
+Session commands use the saved configuration. Keep using the legacy `--resume <session-id>`
+selector for blocking runs that supply configuration, cwd, timeout or Graph options; that selector
+continues accepting a new prompt. `--session <id> --resume` instead requests safe continuation of
+stopped execution. An idle Session prompt can use `--max-steps`; a queued or steering message
+cannot attach a step cap to an existing Turn.
+
+Returning from client-owned MCP interaction and resuming it in another CLI process is not
+supported. Blocking MCP runs retain their existing behavior; `--no-wait` refuses to detach the
+MCP servers owned by that invocation. Graph interaction handoff is also deferred. Use a persistent
+CLI installation for local Session control execution and detached runs; temporary npx invocations
+may own the Host's lifetime and keep the legacy blocking path.
+
+For agent-to-agent CLI workflows, install the repository's `maka-cli` skill after it is available
+on your selected branch. It explains Session coordination; it does not install Maka itself:
+
+```sh
+npx skills add apache/maka --skill maka-cli
+```
+
 ## Upgrade
 
 Update within the nightly line by pinning the exact release (`--target` accepts `latest`,

package/README.zh-CN.md

@@ -108,6 +108,104 @@ maka run --help
 Maka 默认会在执行高权限工具操作前询问。`maka run --yolo` 会授予该任务完整的文件和网络
 权限，只应在你允许任务修改的环境中使用。
 
+
+主代理可以请求结构化结果，或显式提交后返回：
+
+```sh
+maka run "检查这个项目" --json
+maka run "检查这个项目" --no-wait
+```
+
+这两种调用的 JSON 结果都包含 `sessionId`。普通调用仍默认等待并输出最终答案。
+`--no-wait` 在提交被接收后返回；使用会话 ID 查询后续结果。假设返回的会话 ID 保存在
+`$session` 中：
+
+```sh
+maka run --session "$session" --status
+maka run --session "$session" --wait --json
+maka run --session "$session" --answer '["是",null]' --wait --json
+maka run --session "$session" "接下来检查测试" --queue --wait --json
+maka run --session "$session" "重点检查参数解析" --steer --no-wait
+maka run --session "$session" --result --json
+maka run --session "$session" --resume --wait --json
+```
+
+会话控制（`--session`）与继承模型、工作目录一样，继承 Host 已保存的权限。续跑、queue、
+steer 和回答问题不需要重复 `--yolo`，也不会改变执行边界；只有要显式授予完整权限时才加
+`--yolo`。`--status` 会报告 `executionBoundary`：受管 `read_only`/`writable`、bypass 或 external。
+只读任务描述不等于强制只读沙箱，继承 bypass 的会话依然是完整权限。旧阻塞选择器
+`--resume <id>` 对 bypass 会话仍保留显式 `--yolo` 要求。
+
+内置 AskUser 是普通阻塞运行的例外：它会输出问题 JSON 而不是最终答案。脚本应使用 `--json`
+并检查 `status`，不能仅凭退出码 0 判断任务完成。普通内置 AskUser 会以退出码 0 返回
+`needs_input`、问题及选项，Host 保留等待中的 Turn。
+`--answer` 使用 JSON 数组，为每个问题提供一个字符串或 `null`，回答后原工具调用和原 Turn
+继续执行，无需 `--resume`。答案提交失败或结果不确定时不会自动重发；先重新读取当前问题，
+再决定下一步。存在多批待回答问题时会如实报告，无法唯一选择当前批次时拒绝提交答案。
+
+对于 Host 持有的会话执行，`--wait` 和 `--status` 遇到沙箱扩展请求会返回 `needs_approval`，
+并在 `approvalRequests` 中列出 `kind`、扩展范围 `expansion` 和理由 `justification`；内部请求
+ID 不暴露。查看范围后，选择批准或拒绝：
+
+```sh
+maka run --session "$session" --approve --wait --json
+maka run --session "$session" --deny --wait --json
+```
+
+上面两条命令是二选一，不能顺序执行。它们都继续原 Turn，要求会话中恰好有一个待处理沙箱
+请求；没有请求或存在多个请求时拒绝提交决定。它们无需 `--yolo`，也不能与之混用。批准通过
+Host 扩展受管沙箱边界，并保存供该会话后续执行使用，不会将会话切换为 bypass。命令针对
+本次连接时待处理的请求；结果
+不确定时不要自动重试，应先读取当前请求，再决定下一步。普通阻塞运行仍保留原有的沙箱
+边界自动拒绝行为。
+
+协调线程推荐先后台入队，再处理会话交互：
+
+```sh
+maka run --session "$session" "接下来检查测试" --queue --no-wait --json
+maka run --session "$session" --wait --json
+```
+
+工作会话提交回执中的 `submission` 为 `started`、`queued` 或 `steering`，只表示接收方式；`status`
+描述当前观察到的会话，不表示刚提交的消息已完成。排队回执可同时带有 `needs_input` 和当前
+Turn 的问题，或 `needs_approval` 和沙箱请求；先回答交互，后续消息才能执行。`queued` 是观察到
+的后续消息与 steer 总数，不是精确排队位置；回执快照未追上接收结果时省略该计数，
+可用 status 读取新状态。Host 发布重试状态时，status 还会带上
+`providerRetry`，不会根据静默时间猜测活动。
+
+助手 Inbox 会话返回 `submission: "inbox"`，不包含工作 Turn 的结果或队列计数，即使指定 `--wait` 也立即返回接收回执。这仅确认消息已进入 Inbox；委派工作的结果需通过对应工作会话查询。
+
+默认使用 queue，每条显式排队消息对应一个独立后续 Turn。steer 沿用 Host 当前 Turn 的追加
+机制，错过最后处理边界时可能进入后续 Turn。提交排队消息时的 `--wait` 跟踪该消息对应的执行，不会返回前一 Turn 阻塞队列的问题；
+这类问题要通过独立的会话 wait/answer 处理，或采用上面的协调流程。steer 配合 `--wait` 观察连接时选定的
+Turn，不保证追加消息一定在该 Turn 结束前消费。
+单独 `--wait` 在连接时固定目标，空闲时读取最近结果。`--result` 不等待仍在执行的 Turn。
+状态和结果查询不准备模型、不启动 MCP。用 Ctrl+C 退出会话观察会让 Host 继续执行；旧阻塞
+run 的取消行为保持原样。显式停止 Host 执行可用 `maka run --session "$session" --stop --json`。
+停止操作针对连接时观察到的当前 Turn，不需要 `--yolo`，请求成功退出 0。显式或隐式的 status
+查询成功时也退出 0，即使它报告的 Turn 已失败或取消；result/wait 仍以任务失败返回非零退出码。
+停止或查询成功不代表分配的任务已完成。
+
+权限请求、MCP 表单等会话 CLI 无法回答的交互会留在 Host 中等待。wait 会报告实际交互类型和恢复
+命令：使用同一 Host 的交互式客户端处理，或显式停止该 Turn。后台提交成功不保证后续执行
+不会请求交互。
+
+会话控制使用已保存的配置。需要指定配置、cwd、timeout 或 Graph 选项的阻塞运行，继续使用
+兼容入口 `--resume <session-id>` 选择会话并提供新 prompt。`--session <id> --resume` 则表示
+安全恢复已停止的执行。空闲会话的新 prompt 可以使用 `--max-steps`，排队或 steer 消息不能
+给已有 Turn 附加步数上限。
+
+当前不支持客户端 MCP 交互返回后由另一个 CLI 进程续接。阻塞 MCP 运行保留现有行为；
+`--no-wait` 会拒绝脱离本次调用持有的 MCP servers。Graph 交互交接也暂缓。执行本地会话控制
+及后台提交时使用持久 CLI 安装；临时 npx 调用可能持有 Host 生命周期，继续使用旧阻塞路径。
+
+仓库的 `maka-cli` skill 提供主/子代理 CLI 协作指引；待其进入所选分支后可安装。
+skill 本身不安装 Maka CLI：
+
+```sh
+npx skills add apache/maka --skill maka-cli
+```
+
 ## 升级
 
 在 nightly 线内更新时固定精确版本（`--target` 只接受 `latest`、`next` 或精确的 Maka

package/dist/cli-core.js

@@ -316,6 +316,7 @@ export async function runMakaCli(argv = process.argv.slice(2), options = RELEASE
                 ...(command.repairRootAfterRemount ? { repairRootAfterRemount: true } : {}),
                 updateExisting: command.updateExisting,
                 reuseExistingEnvironment: command.reuseExistingEnvironment,
+                ...(command.expectedExisting ? { expectedExisting: command.expectedExisting } : {}),
                 allowInterruptActiveTasks: command.allowInterruptActiveTasks,
                 ...(command.rootPath ? { rootPath: command.rootPath } : {}),
                 ...(command.projectDirectoryRoots

package/dist/run-command-core.js

@@ -16,6 +16,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+import { RunQuestionAvailable, RunSessionInterrupted, } from './run-session-result.js';
 import { randomUUID } from 'node:crypto';
 import { realpath, stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
@@ -25,6 +26,8 @@ import { selectMakaRunSession } from './run-session-selection.js';
 import { sessionEventSandboxBoundaryFailureReason } from './sandbox-boundary-failure.js';
 import { resolveMakaWorkspaceRoot } from './workspace-root.js';
 const VALUE_FLAGS = new Set([
+    'session',
+    'answer',
     'cwd',
     'connection',
     'model',
@@ -36,12 +39,28 @@ const VALUE_FLAGS = new Set([
     'project',
 ]);
 const REPEATABLE_VALUE_FLAGS = new Set();
-const BOOLEAN_FLAGS = new Set(['continue', 'yolo', 'graph']);
+const BOOLEAN_FLAGS = new Set([
+    'continue',
+    'yolo',
+    'graph',
+    'wait',
+    'no-wait',
+    'json',
+    'status',
+    'result',
+    'queue',
+    'steer',
+    'stop',
+    'approve',
+    'deny',
+]);
 export function parseMakaRunArgs(argv) {
     const positional = [];
     const flags = new Map();
     const booleanFlags = new Set();
     let literal = false;
+    const optionArgs = argv.includes('--') ? argv.slice(0, argv.indexOf('--')) : argv;
+    const selectsSession = optionArgs.includes('--session');
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
         if (!literal && (arg === '--help' || arg === '-h'))
@@ -52,7 +71,7 @@ export function parseMakaRunArgs(argv) {
         }
         if (!literal && arg.startsWith('--')) {
             const name = arg.slice(2);
-            if (BOOLEAN_FLAGS.has(name)) {
+            if (BOOLEAN_FLAGS.has(name) || (name === 'resume' && selectsSession)) {
                 if (booleanFlags.has(name))
                     return { kind: 'error', message: `option repeated: ${arg}` };
                 booleanFlags.add(name);
@@ -79,6 +98,71 @@ export function parseMakaRunArgs(argv) {
     if (positional.length > 1) {
         return { kind: 'error', message: 'maka run accepts at most one positional prompt' };
     }
+    const sessionId = flags.get('session');
+    const resumeExecution = booleanFlags.has('resume');
+    if (sessionId !== undefined && !sessionId.trim())
+        return { kind: 'error', message: '--session requires a non-empty Session ID' };
+    if (booleanFlags.has('wait') && booleanFlags.has('no-wait')) {
+        return { kind: 'error', message: '--wait and --no-wait cannot be used together' };
+    }
+    if (booleanFlags.has('queue') && booleanFlags.has('steer')) {
+        return { kind: 'error', message: '--queue and --steer cannot be used together' };
+    }
+    const actions = Number(booleanFlags.has('status')) +
+        Number(booleanFlags.has('result')) +
+        Number(flags.has('answer')) +
+        Number(resumeExecution) +
+        Number(booleanFlags.has('stop')) +
+        Number(booleanFlags.has('approve')) +
+        Number(booleanFlags.has('deny'));
+    if (actions > 1)
+        return {
+            kind: 'error',
+            message: 'choose one of --status, --result, --answer, --approve, --deny, --resume or --stop',
+        };
+    if ((booleanFlags.has('approve') || booleanFlags.has('deny')) && booleanFlags.has('yolo'))
+        return {
+            kind: 'error',
+            message: '--approve/--deny answer only the current sandbox request; do not combine with --yolo',
+        };
+    if (!sessionId && (actions || booleanFlags.has('queue') || booleanFlags.has('steer'))) {
+        return { kind: 'error', message: 'session operations require --session <session-id>' };
+    }
+    if (sessionId && (booleanFlags.has('continue') || flags.has('project'))) {
+        return {
+            kind: 'error',
+            message: '--session cannot be combined with --continue or --project',
+        };
+    }
+    if (actions && positional.length)
+        return { kind: 'error', message: 'session actions do not accept a prompt' };
+    if ((booleanFlags.has('queue') || booleanFlags.has('steer')) && (!positional.length || actions)) {
+        return { kind: 'error', message: '--queue and --steer require a prompt' };
+    }
+    if ((booleanFlags.has('status') || booleanFlags.has('result') || booleanFlags.has('stop')) &&
+        (booleanFlags.has('wait') || booleanFlags.has('no-wait'))) {
+        return { kind: 'error', message: '--status, --result and --stop do not accept wait options' };
+    }
+    if (booleanFlags.has('graph') && booleanFlags.has('no-wait')) {
+        return { kind: 'error', message: '--graph must wait for its final result' };
+    }
+    let answers;
+    if (flags.has('answer')) {
+        try {
+            const value = JSON.parse(flags.get('answer'));
+            if (!Array.isArray(value) ||
+                value.length === 0 ||
+                value.some((v) => v !== null && typeof v !== 'string'))
+                throw new Error();
+            answers = value;
+        }
+        catch {
+            return {
+                kind: 'error',
+                message: '--answer expects a JSON array of strings or null, e.g. ["Yes"]',
+            };
+        }
+    }
     const prompt = positional[0];
     const timeout = flags.get('timeout');
     const maxSteps = flags.get('max-steps');
@@ -112,6 +196,25 @@ export function parseMakaRunArgs(argv) {
     return {
         kind: 'run',
         options: {
+            ...(sessionId !== undefined ? { sessionId } : {}),
+            ...(booleanFlags.has('wait') ? { wait: true } : {}),
+            ...(booleanFlags.has('no-wait') ? { noWait: true } : {}),
+            ...(booleanFlags.has('json') ? { json: true } : {}),
+            ...(booleanFlags.has('status') ? { status: true } : {}),
+            ...(booleanFlags.has('result') ? { result: true } : {}),
+            ...(resumeExecution ? { resumeExecution: true } : {}),
+            ...(booleanFlags.has('stop') ? { stop: true } : {}),
+            ...(booleanFlags.has('approve')
+                ? { sandboxDecision: 'allow' }
+                : booleanFlags.has('deny')
+                    ? { sandboxDecision: 'deny' }
+                    : {}),
+            ...(answers ? { answers } : {}),
+            ...(booleanFlags.has('steer')
+                ? { placement: 'current_turn' }
+                : booleanFlags.has('queue')
+                    ? { placement: 'next_turn' }
+                    : {}),
             ...(prompt !== undefined && prompt !== '-' ? { prompt } : {}),
             stdinPrompt: prompt === '-',
             ...(flags.get('cwd') !== undefined ? { cwd: flags.get('cwd') } : {}),
@@ -140,6 +243,29 @@ export async function runMakaTextCliCore(argv, adapter, overrides = {}) {
         deps.writeStderr(`maka run: ${parsed.message}\n\n${makaRunHelpText(deps.cliCommand())}\n`);
         return 2;
     }
+    if (parsed.options.sessionId) {
+        try {
+            if (!deps.runSession)
+                throw new Error('Session operations are unavailable in this CLI runtime');
+            const options = { ...parsed.options };
+            // Queries and answers must not block reading an unrelated stdin stream.
+            if (options.prompt !== undefined || options.stdinPrompt)
+                options.prompt = await resolveRunPrompt(options, deps);
+            const result = await deps.runSession(options, deps);
+            writeSessionResult(result, deps, options.json === true);
+            const returnsTaskOutcome = options.prompt !== undefined ||
+                options.answers !== undefined ||
+                options.resumeExecution ||
+                options.sandboxDecision !== undefined ||
+                options.wait ||
+                options.result;
+            return result.status === 'failed' && returnsTaskOutcome ? 1 : 0;
+        }
+        catch (error) {
+            deps.writeStderr(`maka run: ${errorMessage(error)}\n`);
+            return error instanceof RunSessionInterrupted ? 130 : 1;
+        }
+    }
     let prompt;
     let selection;
     const workspaceRoot = deps.workspaceRoot();
@@ -176,6 +302,7 @@ export async function runMakaTextCliCore(argv, adapter, overrides = {}) {
     let context;
     try {
         context = await deps.createContext({
+            ...(parsed.options.noWait ? { noWait: true } : {}),
             workspaceRoot,
             cwd: selection.cwd,
             ...(selection.kind === 'existing' || parsed.options.connection
@@ -249,6 +376,7 @@ export async function runMakaTextCliCore(argv, adapter, overrides = {}) {
     let interrupted = false;
     let timedOut = false;
     let streamFailed = false;
+    let question;
     let stopPromise;
     let resolveStopSignal;
     const stopSignal = new Promise((resolve) => {
@@ -310,10 +438,11 @@ export async function runMakaTextCliCore(argv, adapter, overrides = {}) {
         await stopPromise;
     }
     catch (error) {
-        streamFailed = true;
+        question = error instanceof RunQuestionAvailable ? error : undefined;
+        streamFailed = !question;
         graphActivity?.release();
         await stopPromise?.catch(() => undefined);
-        if (!interrupted && !timedOut) {
+        if (!interrupted && !timedOut && !question) {
             deps.writeStderr(`maka run: ${errorMessage(error)}\n`);
         }
     }
@@ -329,6 +458,10 @@ export async function runMakaTextCliCore(argv, adapter, overrides = {}) {
         deps.writeStderr(`maka run: timed out after ${parsed.options.timeoutMs}ms\n`);
         return 1;
     }
+    if (question) {
+        writeSessionResult(question.result(), deps, true);
+        return 0;
+    }
     if (streamFailed)
         return 1;
     if (boundaryFailure)
@@ -337,14 +470,30 @@ export async function runMakaTextCliCore(argv, adapter, overrides = {}) {
         deps.writeStderr('maka run: runtime produced no outcome\n');
         return 1;
     }
+    if (outcome.status === 'running') {
+        writeSessionResult({ sessionId: session.id, status: 'running', submission: 'started' }, deps, true);
+        return 0;
+    }
     if (outcome.status !== 'completed' || outcome.finalOutput === undefined) {
         const detail = outcome.failure?.message ?? outcome.failure?.class ?? 'runtime failure';
-        deps.writeStderr(`maka run: ${detail}\n`);
+        if (parsed.options.json) {
+            writeSessionResult({ sessionId: session.id, status: 'failed', error: detail }, deps, true);
+        }
+        else
+            deps.writeStderr(`maka run: ${detail}\n`);
         return 1;
     }
-    deps.writeStdout(withTrailingNewline(outcome.finalOutput));
+    writeSessionResult({ sessionId: session.id, status: 'completed', finalOutput: outcome.finalOutput }, deps, parsed.options.json === true);
     return 0;
 }
+export function writeSessionResult(result, deps, json) {
+    if (json || result.status !== 'completed' || result.finalOutput === undefined)
+        deps.writeStdout(`${JSON.stringify(result)}\n`);
+    else
+        deps.writeStdout(withTrailingNewline(result.finalOutput));
+    if (result.status === 'failed' && result.error)
+        deps.writeStderr(`maka run: ${result.error}\n`);
+}
 async function resolveRunPrompt(options, deps) {
     const shouldReadStdin = options.stdinPrompt || !deps.stdinIsTTY();
     const stdin = shouldReadStdin ? await deps.readStdin() : '';
@@ -381,11 +530,29 @@ function makaRunHelpText(cliCommand) {
         '  --thinking <level>        off|on|minimal|low|medium|high|xhigh|max|default',
         '  --timeout <seconds>       Invocation timeout',
         '  --max-steps <count>       Tool-step cap',
-        '  --yolo                    Give this task full access to your files and network',
-        '  --resume <session-id>     Continue an explicit compatible task',
+        '  --yolo                    Grant full access; Session controls otherwise inherit saved access',
+        '  --session <session-id>    Select a Session (without a prompt: show its status)',
+        '  --wait                    Wait for this message/current Turn; return input/approval early',
+        '  --no-wait                 Submit and return (Host-owned execution only)',
+        '  --status                  Read current Session status without executing',
+        '  --result                  Read the latest Turn result without waiting',
+        '  --stop                    Request stop for the current Turn (no --yolo needed)',
+        '  --answer <json-array>     Answer the current AskUser, e.g. ["Yes",null]',
+        '  --approve                 Approve the single pending sandbox expansion',
+        '  --deny                    Deny the single pending sandbox expansion',
+        '  --queue                   Queue this prompt as its own next Turn (default)',
+        '  --steer                   Add this prompt to the current execution',
+        '  --json                    Return a structured result, including the Session ID',
+        '  --session <id> --resume   Safely resume stopped execution',
+        '  --resume <session-id>     Legacy Session selector (prefer --session)',
         '  --continue                Continue the latest compatible task for cwd',
         '  --graph                   Run this turn in Graph Mode and wait for graph completion',
         '  -h, --help                Show help',
+        '',
+        'Session controls inherit saved permissions; --yolo explicitly grants full access.',
+        '--status reports the execution boundary; a read-only prompt does not restrict permissions.',
+        'Legacy --resume <id> still requires --yolo for a full-access Session.',
+        '--approve/--deny decide a sandbox request without changing the Session to full access.',
     ].join('\n');
 }
 function defaultMakaRunEnvironmentDeps() {