Repository navigation
tracking(cli): improve the external-agent CLI experience #6168
Description
Problem
When another agent uses Maka CLI as a worker, Session IDs and --no-wait already provide a useful control flow: submit, keep the ID, then inspect, steer, answer, or stop the Session. The gap reported in hands-on use is understanding the progress of a long-running task. A running status and a steering admission receipt do not convey intermediate findings.
TUI /recap already summarizes recorded Session progress through an independent Host model call, including during an active Turn. External CLI callers need access to that capability. Portable Session export serves a different purpose and should not be needed to observe progress.
Desired outcome
Keep the existing Session ID and control model, and improve the caller's ability to understand progress and handle interactions. Track concrete experience improvements here rather than treating one CLI test run as a mandate to redesign every interface.
- Provide Session-based run controls and durable interaction handoff: feat(cli): add session-based run interaction #6133.
- Expose an independent
maka run --session <id> --recap [--json]command (feat(cli): expose running-session recaps #6169). It should return a progress summary during execution without steering or stopping the task, and keep the summary separate from the final result. - Simplify parent-agent invocation, help, result guidance, and the
maka-cliskill; allow compatible options and persistent Session model changes with explicit resume/new input (feat(cli): simplify Session controls and persist model selection #6170). - Validate caller-mediated AskUser and sandbox approval flows with a real provider, documenting the caller's action at each handoff. Automated coverage in feat(cli): add session-based run interaction #6133 is separate from this hands-on acceptance work.
- Align denied-approval outcome reporting (fix(cli): preserve Runtime outcomes and explicit JSON errors #6171): a real Session returned
completedfrom status butfailedfrom wait/result (unresolved sandbox boundary). Keep lifecycle and outcome semantics explicit. - Return compact structured errors (fix(cli): preserve Runtime outcomes and explicit JSON errors #6171) for
--jsonHost-operation failures as well as terminal provider failures, preserving original error information without CLI cause classification. - Review Session export diagnostics and guidance so users can distinguish portable export/offline snapshot requirements from live progress queries.
Recap acceptance: text and JSON output, no stdin blocking, fresh independent model generation, unchanged Turn identity/queue/permissions, visible generation errors, and cancellation that leaves Host execution running. Explain that a recap summarizes recorded evidence, consumes model usage, and is not a direct reply from the running worker.
Alternatives or workarounds
--status remains useful for lifecycle and pending interactions. --steer changes the running Turn's input and its receipt is not a progress reply. session-export is a portable bundle operation. A dedicated worker-to-parent message channel can be evaluated separately if evidence-based recap proves insufficient.
Related existing work: #6119 / #6120 (Session discovery) and #5958 / #6036 (transcript export); this tracker does not replace those contributions.
Prepared with Codex at the contributor's request.
GitHub native stack #6172: #6169 → #6170 → #6171. Review fixes for executor model changes and unchanged native targets are in #6170 (e6036a1b2c).
- Fix native AskUser stop ordering (fix(runtime): settle stopped AskUser tools before terminalizing #6174): stopping a pending question drains Host with an unsettled tool operation, with recovery sometimes reporting
outcome_unknown. Reproduced with officialgpt-6-luna; keep storage terminalization invariants and handle settlement in Runtime/Host.
Activity
me2seeks commentedon Oct 19, 2026
Real-provider acceptance completed against #6170 head
5c6c1a1987c560b3e4817751133172c58923a5f8(stacked on #6169), using the built production CLI, an isolated XDG profile, and the existing selected account. The user's original Host and active tasks were preserved.Verified as a parent-agent workflow:
--status --recapreturned a stage summary in 4.177 seconds; the worker continued its original review.sandbox_boundary_required; the CLI returned the exact path/write/subtree request; approval allowed the retry; the parent read back the expected file.submission: "queued"together withneeds_input; answering the current task yielded its result, then a later wait yielded the queued task's result.--resume --no-waitthen completed successfully. No CLI failure classification or automatic fallback was needed.Two concrete follow-ups remain:
--statusreturnedcompleted, whereas--result --json/--wait --jsonreturnedfailedwithTurn encountered an unresolved sandbox boundary, exit 1, for the same latest Turn. The current status path reads root lifecycle; result additionally applies the sandbox outcome classifier. Reconcile or explicitly distinguish those contracts without making lightweight status replay the entire transcript or guessing failure causes.--jsonreturned empty stdout and human stderr; terminal provider failures returned structured JSON. Preserve the Host message/code in a compact error envelope consistently, without quota-specific policy.Source-grounded self-review found no new blocking defect in the submitted diffs. The worker's proposed thinking-reset concern matches existing Desktop behavior; its missing-validation concern was disproved by Host validation and the live unknown-model probe. This is AI-assisted self-review and does not replace independent human review.
Prepared with Codex at the contributor's request.
me2seeks commentedon Oct 19, 2026
Combined-stack native CLI experience with the user's requested OpenAI official
gpt-6-lunais complete. Two real Maka Sessions reviewed different PRs, then cross-checked each other's reports under this parent coordinator. AskUser and exact path approval requests were serviced by the parent. After the user requested direct CLI use, subsequent control calls usedmaka rundirectly, without a Python invocation wrapper.Verified:
--deny --wait --jsoncontinued waiting until the model successfully read HEAD and completed; status/result agreed on completed.exit 7remained recoverable tool errors; a subsequent Read succeeded and the Turn completed.gpt-6-lunaon that Session and explicitly resuming completed the task. No automatic CLI recovery was involved.--max-steps 1Turn failed with the existing Runtime classtool_step_cap_reached. This exposed a presentation bug: the stored Turn already haderrorClass, but a generic fallback masked it. Fixed in fix(cli): preserve Runtime outcomes and explicit JSON errors #6171 commit008bb67dd3; direct CLI result now returns the existing class when no original message exists. 67 affected outcome/adapter/activation tests passed, along with CLI build/typecheck and lint/format checks. No new error classification was introduced.Separate reproducible Runtime issue: stopping a native Turn while AskUser is pending drains the Host. Reproduced three times, including with a foreground production Host and a single active Turn:
gpt-6-lunatask whose first action is AskUserQuestion and wait forneeds_input.maka run --session <id> --stop --json.{error:"Runtime Host is draining",code:"host_draining"}.unexpected turn.stop failure: Error: Cannot terminalize invocation ... with unsettled tool operation toolop_...fromSqliteRuntimeStore.importRuntimeEventSync. Recovery has also producedfailed/outcome_unknown; other active test work was cancelled during drain.Investigate native AskUser tool settlement before invocation terminalization. Keep the storage invariant; do not work around it in CLI. The three PRs do not modify Runtime/Host/storage relative to their base, so this is recorded as a separate stop-path issue rather than attributed to the CLI changes. Existing FakeBackend stop tests did not cover this native behavior.
The reviewers found no other verified blocking defect. One reviewer correctly limited its initial step-cap conclusion until the parent supplied the matching Host + persisted transcript evidence. Cross-review also corrected an overly strong claim that every executor configuration callback must return a confirming snapshot: the interface permits void, so completion and snapshot confirmation are distinct. Neither automated review constitutes independent human approval.
Prepared with Codex at the contributor's request. Test sessions used an isolated profile; the original user Host and defaults were preserved.
me2seeks commentedon Oct 19, 2026
Codex update: the native AskUser stop defect is fixed in #6174 (
ccfea27ba2), independently based on main.Confirmed on main with a production Host/native-backend regression: the normal interaction closure bypassed tool T2 settlement, then storage rejected terminalization with an unsettled operation. The fix commits the known aborted tool result before rethrowing the same control signal. Storage guards and invariant/fail-stop behavior remain intact.
Local validation: 196 focused tests, 89 overlapping broader ToolRuntime/RuntimeKernel tests, full build/typecheck/lint/format, Desktop/UI knip, ASF headers and Windows inventory passed. The real official
gpt-6-lunaCLI repro now stops without draining, with Host ready and canonical Turn cancelled; the same Session then completes a new prompt withstop-recovered. Isolated credentials were removed and the original user Host was untouched.The tracker item remains open pending review/merge. This is separate from the CLI output simplification stack #6172.