git-on-my-level/agentctl/agentctl-portable

agentctl portable

Use agentctl for deterministic routing, normalized execution state, durable callbacks, explicit Multica promotion, and selected shared context. Native CLIs still own prompts, sessions, models, tools, and correctness. Multica still owns durable issues, runs, assignment, and review.

For optional coordination integrations, agentctl identity --json reports versioned provider/native-conversation evidence without probes or writes. Unknown IDs remain null. Native session IDs are provider-scoped hashes, not resume handles or authenticated agent principals; consumers add their enrolled host namespace and preserve explicit coordination identity. Installed harnesses are inventory only. Generic agents do not need agentctl to register elsewhere.

Resolve the binary from AGENTCTL_BIN, PATH, or $HOME/.local/bin/agentctl. If it is unavailable, stop with dependency_unavailable; do not inspect native session stores as a fallback.

Default launch

Kick off a new native agent with delegate, not run. For an explicitly requested model, use delegate with a schema-versioned request file and only the user's constraints. Read help delegate, plan with --plan, then execute the same request and key with --wait --content (remove --plan). Do not reconstruct a native model slug from an alias. Bare adapters or missing remote runtimes are unresolved constraints, never substitution grants.

agentctl help delegate
agentctl delegate --request-file request.json --prompt-file task.md --plan
agentctl delegate --request-file request.json --prompt-file task.md --wait

Inspect native.argv, native.env, and native.permissions on the plan before launching. Coding is the default access. It adds Cursor --force, Codex --dangerously-bypass-approvals-and-sandbox, Claude Code --permission-mode auto, and Devin ACP permission approval only when delegation.unattended_coding_permissions is true. settings.access: "read_only" never adds those flags; Claude Code and Devin refuse it. Expert run does not apply this grant. Do not hand-write cursor or codex argv for a new agent, and do not edit a global CLI allowlist to widen permissions.

Hermes terminal processes, Claude Code Bash tasks, and Codex terminal sessions can own a foreground agentctl process using their supported process lifecycle. Retain that process handle and collect its completion. run --background is rejected since v0.6.0. Use explicit Multica dispatch for durable task ownership. The delegate plan reports ownership and collection semantics before launch.

For an external scratch prompt, replace --prompt-file with --prompt-stdin and redirect the file into agentctl. Only expert run accepts --prompt-delivery; preserve its verified delivery. delegate, continue, steer, and dispatch use their own delivery contract and need only --prompt-stdin. Fanout repairs change the shared or child manifest prompt_file within the manifest directory. An error includes a structured repair; it never copies prompt bytes into logs.

For results, prefer result <id> --content for exact text, --summary for compact metadata, and result --unreconciled --summary for bounded bulk collection. A pending result supplies an await action. Check the agentctl exit status and JSON ok before inspecting fields; piping through head can hide a failing exit code. Completion, delivery, and acceptance remain distinct.

A failed dispatch retains last_operation_failure in status. Resolve its category and retry the original inputs with the original idempotency key. Uncertain remote creation is never a reason to allocate a new key. update status distinguishes observed binary version from installation records; inspect bootstrap and supervisor status before treating an update as complete. A failed installer reports rollback separately from bootstrap assets retained. For a legacy skill collision, help bootstrap adopt describes a read-only plan and explicit digest-bound adoption with a backup. Never overwrite custom skills. A supervisor holds one state-directory lock through shutdown. Existing custom launchers require explicit hash-bound wrapper registration; ordinary upgrades preserve registered wrappers and refuse drift.

Discover just in time

Start with the one question relevant to the task:

agentctl doctor
agentctl help <topic>

Useful topics include delegate, run, dispatch, recent, fanout, result, await, continue, steer, subscribe, capabilities, bootstrap update, skills, promote, knowledge, and context. Follow returned read-only next_actions for deeper discovery. Do not preload every topic or memorize version-specific flags in place of help.

agentctl bootstrap update reconciles the embedded portable skill and a short delegation pointer in detected harness instruction files. It appends a marked block to existing unmarked files, creates missing documented files except OMP, and repairs truncated or duplicate agentctl markers. Opt out with bootstrap.instruction_pointers=off or --no-instruction-pointers. Use --dry-run when inspecting another home or narrowing an unfamiliar installation.

Exact release builds default to automatic updates. The first work-creating invocation due on each UTC day starts a detached short-lived worker that verifies the matching release archive and uses its packaged installer for managed installations; it does not delay the foreground command or create a daemon. Commands advertised as read-only never trigger this maintenance. Use agentctl update status to inspect it. agentctl update policy notify retains the once-daily agentctl_update_available prompt without installation, and off disables all checks.

Choose authority deliberately

Use direct native work for bounded investigation, scoping, and operations. Use Multica for durable changes, PRs, multiple owners, review, or work that must survive the parent. When uncertain, ask agentctl route explain -- "<host?> <model>". Pass only the short host/model selector, not task prose or nested delegation instructions. It returns ranked reviewed hits plus a placement mode; empty lists mean nothing was recognized, not an error. It never launches work, verifies a remote runtime or Multica assignee, or creates an exec-* handle. If this_host is not configured, local versus remote placement remains unknown. Use dispatch when the selector names one configured host and one concrete model and the task should be created under Multica authority. Work created directly in Multica remains outside the host-local journal.

Never infer a capability from an adapter name. If doctor or capabilities says a requirement is unavailable, report it; do not weaken the operation, invent a native command, or scrape private harness state.

Structured delegation: default for new agents

Read agentctl help delegate before run. Translate the user's explicit constraints into a request; leave everything else absent. The selector must include at least family or model; an empty selector is refused during parsing with delegate_invalid_request, before resolution or launch. “grok” means {"family":"grok"}; “cursor grok 4.6” means {"harness":"cursor","family":"grok","version":"4.6"}. Other word orders produce the same constraints. Never guess a version or native slug from memory. Add explicit speed/effort under settings when requested. settings.auto_compact_window (for example "300k") sets a Claude Code lane's compaction window for that launch; other harnesses refuse it.

{"schema_version":1,"request_key":"review-01","selector":{"family":"grok"}}

agentctl delegate --request-file request.json --prompt-file task.md --plan
agentctl delegate --request-file request.json --prompt-file task.md --wait

Agentctl resolves reviewed preferred entries, fills compatible defaults, and builds native flags. Inspect requested, resolved, and provenance. Conflicts or ambiguity launch nothing; use returned candidates to resolve only the missing choice. Config needs explicit family/version metadata. Omitted host or local selects this machine; route.this_host optionally supplies its configured name. Workspace trust is a separate delegation.cursor_workspace_trust grant. With it, both coding and read-only Cursor recipes add --trust; read-only delegation refuses before launch without it (workspace_trust_required). Trust is never implied by a model preference. Unattended coding permissions are a separate delegation.unattended_coding_permissions grant. When it is true, coding launches (omitted settings.access, or "coding") include Cursor --force, Codex --dangerously-bypass-approvals-and-sandbox, Claude Code --permission-mode auto, and Devin ACP permission approval. Set settings.access to read_only for Cursor --mode ask and Codex --sandbox read-only; that access never receives the coding permission flags. ZCode read_only (reviewed for CLI 0.17.0 only) runs plan mode with a tool denylist, a private empty HOME, and a launch-scoped .zcode/config.json; it refuses (zcode_read_only_unavailable) on another version, a prompt starting with /, a relative executable, a non-canonical cwd, or zcode.json, .zcode/config.json or .env in the cwd or an ancestor. Claude Code refuses read_only because no reviewed mode guarantees blocking edits and shell writes in --print. Without the coding grant Claude Code adds no permission flag and reports permissions: constrained; with the grant it still reports constrained: auto mode retains native classifier checks and can deny tool calls. Devin refuses read_only: ACP read-only enforcement is unverified. Devin ACP requires a nonempty UTF-8 prompt via agentctl-managed stdin; invalid text or delivery is refused before launch, including read-only plans. Expert ACP runs require --prompt-delivery stdin with a prompt source. Its frozen AGENTCTL_DEVIN_ACP_APPROVE entry controls one-operation approvals. Denials select an offered reject_once option and surface attention; cancelled is reserved for client cancellation or a denial with no reject option. The stored answer keeps the final assistant message: the next message after tool activity replaces earlier narration. Completed Devin ACP turns can continue only when the server advertises loadSession; print mode cannot continue. Devin steering remains unavailable until a real cancel plus reprompt route is verified. Devin ACP verifies the configured model id against the session's model option before the prompt; a fuzzy native match fails with acp_config_value_unavailable. devin-cloud is a separate harness, reached only by naming it: it runs a Devin cloud session through devin acp --cloud, verifies devin_version (the configured model) and repos (the GitHub origin of --cwd) before the prompt, works from the pushed remote rather than the local tree, records session_url, and is never a workspace owner. A family shared by local and cloud entries is ambiguous. Harnesses without a reviewed unattended permission recipe report permissions: unsupported and are not given an inferred flag. Unavailable settings or hosts must not trigger silent substitution or fallback to expert run.