Start an orchestration run by posting a task to the Bernstein server.

A run executes real work and takes minutes to hours. This call returns as soon as the run is queued, not when it finishes. Do not re-issue it while waiting: that starts a second run. To follow the run, wait poll_after_ms and then call bernstein_run_status, passing either the returned task_id or the returned run_id. Poll it until status is terminal (completed, failed or cancelled).

Args: goal: Description of what you want Bernstein to accomplish. role: Specialist role to assign (backend, frontend, qa, security, …). priority: 1=critical, 2=normal, 3=nice-to-have. scope: Task scope - small, medium, or large. complexity: Task complexity - low, medium, or high. estimated_minutes: Rough time estimate in minutes. parent_task_id: When set, the run is created as a subtask of this task, and the parent transitions to waiting_for_subtasks.

Returns: JSON with the created task ID, title and status, plus the run_id naming the run journal and the advisory poll_after_ms delay before the first poll. When the call itself is task-augmented (the client sent task in the request params), a Tasks-extension CreateTaskResult is returned instead so the client can poll the run.

Liveness, task counts, cost, and an optional filtered task list.

One read answers the whole "how is the server doing" question: the tool responding at all is the MCP liveness check, counts carries the task totals, cost the USD spend, and passing status appends the matching tasks. detail switches the per-role and per-task rows from compact to full.

Args: status: Optional task filter - open, claimed, in_progress, done, failed, blocked, or cancelled. When set, the matching tasks are included under tasks. detail: Include the full per-role breakdown and, with status, the full task rows instead of compact ones.

Returns: JSON with live, counts, cost, and optionally per_role / status_filter / tasks. A task-server outage still answers with live: true plus an error.

Claim the next eligible task and return a verifiable claim receipt.

Drives the dependency-gated claim path: a task is offered only when every id in its depends_on is present in completed_ids. Unlike a raw claim, the result is a signed, content-addressed claim receipt the worker holds and can re-verify offline against the audit chain (bernstein audit verify), not a mutable task projection. A filter that matches no eligible task returns a signed refusal receipt - a claim attempt is never a silent skip.

Args: claimer_id: The claiming worker's identity. role: Only claim tasks for this role (e.g. backend). project: Only claim tasks in this project namespace. capability: Only claim tasks requiring this capability. completed_ids: Task ids whose dependencies are satisfied; a task is eligible only when all of its depends_on are listed. max_attempts: Skip tasks at or above this attempt count. claimer_card_fingerprint: sha256: fingerprint of the claimer's agent card key, bound into the receipt.

Returns: JSON of the signed claim receipt (taskId, granted, backlogHead, filterDigest, chainHead, receiptHash, signature, pollToken, ...).

Post a message to a task's mailbox as a signed journal entry.

Wraps the worker mailbox: the message is DLP-redacted, HMAC-chained onto the mailbox journal, Ed25519-signed, and mirrored to the audit chain (task.mailbox_message) before returning. The result IS the signed journal entry - a worker holds a progress record it can verify offline against the same chain bernstein audit verify walks, not a bare status string. This tool never changes a task's fields; it appends to the task's mailbox.

Args: task_id: The task the message is addressed to. body: The message body (<= 4096 bytes). sender: The posting worker's identity. kind: Typed message kind - one of finding / artefact_ref / question. sender_card_fingerprint: sha256: fingerprint of the sender's agent card key.

Returns: JSON of the signed mailbox journal entry (seq, prev_entry_hash, entry_hash, signature, signer_public_key_pem, body_hash, ...).

Attach a journal-anchored artifact to a task you hold the claim for.

The artifact is stored content-addressed, sealed into the lineage spine, appended to the task's Merkle-chained journal, and mirrored to the audit chain. The returned record IS the receipt: its identity is the spine entry hash, and any reviewer can re-verify the content hash offline against the same chain bernstein audit verify walks. Reposting a key appends a new version chained to the prior one. There is no way to set progress here - progress is a chain-computed projection of journaled work, never postable.

Args: task_id: The task to attach the artifact to. You must hold its claim. key: The artifact slot; reposting a key appends a new version. artifact_type: One of report (markdown body), table (columns + rows), or link (url + link_kind). poster: Your claim identity; posting against a task you do not hold is refused and the refusal is audit-recorded. body: Markdown body, for report artifacts. columns: Column headers, for table artifacts. rows: Rows of cells, for table artifacts. url: The URL, for link artifacts. link_kind: The declared link kind - preview / dashboard / document - for link artifacts.

Returns: JSON of the chain-anchored artifact record (key, version, content_hash, spine_entry_hash, journal_index, ...).

Cancel one task and its subtask tree; the orchestrator keeps running.

Posts to /tasks/{task_id}/cancel, which cascades through the subtask tree (parent_task_id references) so children are not left running after the parent is aborted. Cancellable statuses are open, claimed, in_progress, blocked, waiting_for_subtasks and planned. A task already in a terminal state is reported with its current state rather than cancelled again, and an unknown task id is refused. To stop the whole orchestrator instead, use bernstein_shutdown_orchestrator.

Args: task_id: The root task to cancel. Its descendants are cancelled with it. reason: Optional reason recorded on the cancellation.

Returns: JSON with the cancelled root task, its status, and the count of cascaded descendants - or the task's current state when it was already terminal.

Shut down the ENTIRE Bernstein orchestrator for this project - every run, every worker - not one task; to stop a single run and keep the orchestrator alive, use bernstein_cancel instead.

Writes .sdd/runtime/signals/SHUTDOWN in the project directory, which the orchestrator detects and shuts down gracefully.

Args: workdir: Project root directory (default: current directory).

Returns: Confirmation message.

Sign off a finished result that is waiting on a decision.

The tool reads the task first and acts only on pending_approval: the work has run, the result is held for a decision, and accepting it completes the task with note as the result summary.

Every other status is refused with a structured error naming the current status, and no state-changing request is sent:

• planned - the task is held by plan mode. That decision is recorded on the plan, not on the task, so approve the plan (bernstein plan approve <plan_id>). Releasing one task would start the work while the plan is still undecided.

• open, claimed, in_progress, blocked, failed, terminal states, ... - there is no approval to grant. Use bernstein_complete to report work you are executing, bernstein_update to report a blocker on the task mailbox, or cancel the task to abandon it.

Args: task_id: ID of the task to approve. note: Approval note recorded as the result summary.

Returns: JSON with the task id, its new status, and which approval was granted - or a structured refusal naming the current status.

Report the result of work you are executing.

This is the completion verb of the MCP worker loop (claim with bernstein_claim, report with bernstein_update, finish here). The tool reads the task first and completes it only from a state a worker holds it in (open, claimed, in_progress).

It is not a way to clear a task out of the way. A parent in waiting_for_subtasks is completed by its subtasks finishing, an orphaned task belongs to crash recovery, and a result already awaiting a decision is signed off with bernstein_approve; all three are refused with a structured error naming the current status. Report only work that actually ran, and use bernstein_update when the task is unfinished or stuck.

Args: task_id: ID of the task to complete. result_summary: What the work produced. The task server rejects an empty summary and fails the task instead.

Returns: JSON with the task id, its new status, and the recorded summary - or a structured refusal naming the current status.

Return a verifiable Tasks-extension handle for a run, by run id.

The handle's status is a pure projection of the run journal, and it embeds the run's audit-chain head so the client can later verify the task it watched corresponds to the audited run (bernstein audit verify or the offline verifier). Polling is stateless: any server instance reprojects the same handle from the on-disk journal. A poll that carries a progressToken also receives a notifications/progress tick derived from the journal fold, and only when the fold strictly advanced since the previous tick.

Args: run_id: The run to project. Either identifier bernstein_run returned is accepted: the task_id, or the run_id naming the journal. Resolution is journal run id first, then the task id slugified into a journal run id, so the two forms reach one journal and project an identical handle. Must be a plain identifier - path separators and traversal are refused. workdir: Project root directory (default: current directory).

Returns: JSON of the Tasks-extension task-handle body (taskId, runId, status, journalHead, chainHead, receiptHash, pollToken, ...).

Return the worker's context capsule, optionally verified offline.

Args: task_id: The task whose capsule to read. Must be a plain identifier - path separators and traversal are refused. workdir: Project root directory (default: current directory). verify: When true, recompute the capsule offline from the run journal and audit chain and include the verdict.

Returns: JSON of the capsule projection (and, when verify is set, the offline verification result). A mock-layer fixture is reported as such and never verifies as real.

Discover skills, or load a named skill body, reference, or script.

Omit name to receive the compact skill index. Pass a skill name to fetch its full SKILL.md body. reference and script are valid only with a named skill.

Args: name: Optional skill name (for example "backend"). reference: Optional filename under references/ - for example "python-conventions.md". script: Optional filename under scripts/ - for example "lint.sh". The script content is returned as text; the MCP harness does not execute it.

Returns: The compact index when name is omitted; otherwise JSON with name, body, available files, and optional fetched content.