MCP and results

Use this reference to understand what your agent can ask discerndiscern↗A tool that installs and runs an agent development practice in a project. to do, which result confirms the outcome, and where your approval is required. It lists exact MCP inputs, result formats, schemas, exit codes, and continuation limits.

The gateGate↗The configured checks a change must satisfy for ordinary completion. is the project's final quality check. Proof records its evidence for one exact commit. The trunkTrunk↗The shared branch that accepted work joins, usually main. is the project's shared branch. Checkpoints ask for judgment; grants record your permission to land changes.

Project-operating tools require a configured project. discern_docs can read the bundled manual without one. To connect an agent, follow Connect a coding agent.

Every result describes the same operation and verdict, whichever presentation you choose.

Choose by task and consumer. Markdown offers prioritized prose for reading and quoting; JSON offers exact fields for selection, validation, scripts, and durable integrations. Either may suit people or agents.

MCP carries both representations because hosts expose channels differently. Either content[0].text or structuredContent explains the current state and next action; together they remain complementary rather than duplicate JSON.

All surfaces preserve one completion verdict. ok: true means every required outcome declared for the verb holds. Optional degradation stays successful only as a typed advisories[] item with a kind, evidence, and next action. A required late failure remains false even when its steps or data show earlier effects, and MCP isError is the inverse of structuredContent.ok. Renderers select and arrange facts; they never reinterpret success.

--markdown, --json, and --render are mutually exclusive. All suppress surrounding terminal decoration and subprocess narration. The convenience-only --render passes authored Markdown through discern's terminal renderer. It never prompts or pages, follows width, theme, color, and character support, and redirects without control sequences. JSON and Markdown remain the primary result formats.

An authored Markdown presentation selects facts from the registered result contract. It does not dump every JSON field. When present, sections occur in this order: current state, bounded evidence, authority and boundaries, owner attention, other actions, then the next action. Owner attention contains decisions reserved for the owner. If several caller actions matter, secondary actions come first and the immediate next action closes the document. Whitespace-significant supporting payloads retain their exact content inside the evidence section, including leading and trailing spaces. These payloads include requested mapMap↗The project's account of how its software works and why. or manual pages, setup instructions, diagnostic output, and terminal art.

status has an additional size boundary. Its default CLI JSON, MCP structuredContent, and live resource are bounded orientation projections with true omitted counts. discern status --verbose --json and discern_status with verbose: true select full structured status. Both default command surfaces advertise that route in hints; Status and session hints defines the fields and caps.

Default doctor JSON and discern_doctor return environment and actionable checks without data.execution_model. Their hint names discern doctor --verbose --json; MCP accepts verbose: true. Human doctor uses --verbose for per-step hints.

setup begin emits the operating contract and first page; setup step <n> emits one page. Each shares its parsed operational spine across structured, human, and Markdown surfaces. setup done returns Proof, assurance, derived inventory, and one phase-valid action.

Model Context Protocol (MCP) lets a coding agent call discern directly. The tools below use the same result contracts as the CLI. Use their structured fields for integrations and their Markdown for reading or relaying the outcome.

The input object is strict: undeclared keys are rejected. Accepted keys are listed below; each tool's schema marks which are required.

Ordinary completion requires a clean, committed tree and proves its HEAD. standalone: true provides transient diagnostics, including on dirty trees, without Proof. policy_base accepts a fetched comparison ref only together with ci: true and standalone: true, for a hosted report. rerun: true measures an unchanged tree again. met and unmet record checkpoint conclusions; ci: true cannot be combined with them. None of these options grants landing authority, and none changes which checkout the agent works in.

Your agent omits action for ordinary acceptance. From the effort's worktree, the call records the effort's submission, the exact HEAD and its Proof, and lands it when authority is verified. Without authority it refuses read-only, the submission waits in the landing queue for you, and the agent relays the Proof lineProof↗discern's completion evidence for the exact committed change it validated.. The target selects a task by id, path, branch, or full local ref; the main checkout requires one. Consent covers only that submitted commit. confirmed: true records consent given in the current conversation; variance and approve_standard each require it. dry_run: true shows the landing queue and the selected task's verdict without changing anything. When the trunk moved after the task's Proof, the call composes and checks the combined code in an integration worktreeIntegration worktree↗A disposable worktree a landing creates for itself when the trunk moved after a submission's Proof. and lands the exact proven result. A conflict or failed combined check returns to the author; a checkpoint question about the combined result retains the composition and is answered through met (or unmet with its rationale) on a follow-up call, continuing the same landing. The refusal serves a composition_receipt that the answer — and a varianceVariance↗The owner's permission to land a change despite a stated unmet checkpoint. decision over the combined result — must name, so a decision never drifts onto a composition it was not served for.

If checkpoint questions block emergency planning, your agent first supplies action: "emergency", prepare: true, and the reason. Preparation runs checkpoint triggers and serves their questions without running validation jobs. The agent records satisfied served questions through met, an array of checkpoint ids, and receives a preparation receipt. That receipt goes into preparation_receipt on the later preview and confirmed call. Changed revisions or declarations require fresh preparation; an unmet question still blocks emergency integration. dry_run: true previews preparation without running triggers or recording answers. Preparation cannot be combined with confirmation or transition recovery.

For emergency integration, your agent calls discern_accept with action: "emergency" and a reason. You review the displayed trunk, repair revision, reason, and checks that failed, never ran, or have stale evidence before your agent supplies confirmed and the plan's approval_token. The token expires after 15 minutes; a changed plan needs fresh approval. The repair must include actual trunk and exclude other unlanded efforts. Checkpoint judgments and protected policy remain prerequisites. The exception has its own record type and cannot serve as passing Proof. This action does not push, deploy, or change external branch protections. recover resumes an interrupted emergency by landing id.

Every project-operating tool accepts an optional path that selects the discern project or worktree for that call. Pass an absolute filesystem path anywhere inside the intended checkout, including another repository in a multi-repo workspace. discern resolves the project root. Omit path to use the checkout the MCP server currently targets. Relative paths are rejected because the server's process directory is not the caller's directory. discern_docs needs no project. After a successful discern_start, later calls use the new worktree by default. After discern_accept removes that worktree, the server re-aims at the surviving main checkout.

Tools that require completed setup return a controlled setup_unfinished result until setup finishes. A tool rejects undeclared input keys instead of dropping them.

discern_standards requires an action. action: "measure" accepts names, force, and pin. action: "propose" accepts an ordered proposals array of unique { name, reason } entries and records every simultaneous breach in one transaction. Proposal reasons are technical justification, not approval or landing authority. The scalar discern standards propose CLI command remains available for terminal compatibility.

discern_refresh accepts dry_run: true. Its plan covers agent files, materialized skills, integrations, Proof noteProof note↗A durable copy of landed Proof, attached to the commit in Git. Git config, removals, and planning errors; preview has no steps. A normal call applies only those targets and reports steps.

MCP tools/list returns full definitions. Clients choose the startup context. The deliberate eight-tool discovery prefix is status, start, prepare, done, update, await, accept, and map. Progress follows it; the expensive standalone test remains on demand after progress.

Cursor's strict profile keeps discern_await below the Agent CLI's 60-second transport limit. Gate calls can take longer, so run discern done --markdown in a shell; use the corresponding discern prepare --markdown or discern test --markdown command when those stages are the intended operation.

The long profile reserves 300 seconds for delivery and cancellation. The strict profile reserves 15 seconds against Cursor's shortest verified surface. A watch returns immediately when its condition holds. When the budget expires first, the result is ok: true, data.met: false, and includes a 15-character data.resume handle. Continue with that handle; do not rebuild the watch from observed state. Handles are repository-local, expire after 7 days, and share a 512-record cap. CLI reports the not-yet result with exit 124; MCP returns a normal tool result. timeout may shorten a call but cannot extend its selected profile.

Every done, test, standards, and accept run, and every discern_await call, announces a progress handle as its first progress fact, in the form R1-XXXX-XXXX-XX, together with the command that reads it back. The same facts reach a live terminal, MCP notifications/progress messages when the client supplies a progress token, and a journal under the repository's Git administration. A --json or --markdown run prints nothing while it runs; its result envelope is its whole output.

An unfinished completion attempt holds a 60-second lease that its live operation renews every 20 seconds. If another done reaches the same evidence while that lease is current, the result is error: "incomplete", failed_stage: null, and gate_ran: false. data.completion.pending contains one row for the shared attempt, including its attempt id, effective expiry, progress handleProgress handle↗The short R1-XXXX-XXXX-XX code recorded for a long operation and announced to MCP callers. when available, and next action. Read the existing operation with discern_progress, or discern progress <handle> in the CLI; do not start another gate. A later invocation cancels a claim immediately when its journal executor is gone, or after renewal expires when liveness is uncertain, then proceeds with a new fenced attempt.

discern progress [handle], or discern_progress with handle and path, reads that operation back at any time. Reading changes nothing. With no handle it reads the most recently started operation of the calling checkout; another checkout's operation is refused by name. Records are kept for up to 7 days in a store shared by every worktree of the repository, with a bounded capacity that evicts finished await records first and keeps a running operation while anything finished can go.

Active waits stay visible when independent checks finish. The current state explains what cannot start, why it is waiting, elapsed waiting, and what happens next. Capacity waits include the configured concurrent-run limit and the latest observed use. A live process alone does not establish advancing work. Older records without wait facts cannot supply this information.

When your agent returns to a checkout with an operation still running, discern_status includes the same current-state summary and the command to read it back. A queued operation therefore remains visible through status as well as progress.

An active await records its target, requested condition, latest observation, and continuation. If the call stops, the agent can use that continuation to preserve the original watch. The agent should read the original call's progress before starting another watch. An elapsed observation window means the condition remains unmet; it does not mean the awaited work succeeded. Explicit cancellation ends automatic waiting.

Observers and executors differ. A reconnect read, an await watch, or a second session can stop, time out, or die without touching the run. The MCP call that is itself executing a verb is not a separate observer: its explicit cancellation, or its transport closing, cancels the executor, and the journal records the run as cancelled with its facts retained. Refusals name their condition: a damaged or unknown handle, an empty store, another checkout's operation, an unreadable record, a record written by a newer discern, or no reachable repository.

A project's own check, such as its test or build command, may report its progress by printing lines to stdout or stderr:

DISCERN_PROGRESS {"units":{"kind":"partitions","completed":3,"total":8},"results":{"passed":120,"failed":1,"skipped":2},"elapsed_ms":45210}
DISCERN_PROGRESS {"failure":{"name":"alpha holds","message":"expected 2, got 3","file":"tests/alpha_test.py","line":42,"reproduce":"tools/test --only 'alpha holds' --seed 7"}}

One JSON object per line; every field is optional. units carries kind, completed, and total, where null or an omitted total is a valid unknown total. results carries only the counts the producer established; an absent or empty results leaves the counts unknown. active lists running work labels, elapsed_ms is the producer's own elapsed time, and partial: true marks counts that cover only part of the completed units; once reported, a producer's counts stay marked partial. A failure names the failing test or obligation with its message, file, line, and a focused reproduce command carrying the recorded seed and instrumentation. discern presents the counts and failures live and keeps them for reconnect; the lines change nothing about scheduling, verdicts, or evidence. Unknown keys are ignored, a line that does not validate completely is ignored whole, and lines over 16 KiB are dropped. The protocol is the same for any language or runner.

discern_map and discern_docs expose the same discovery funnel:

A search result carries target, path, section, title, description, match, an optional matching heading, and a contextual snippet. match is complete, partial, or metadata. The enclosing payload carries query, optional scope, the full match count, truncated, and the returned results. A zero-match search is ok: true with an empty result list. Scores remain an implementation detail.

Lexical matches with match: "complete" rank first. When fewer than five qualify, strong partial matches can fill the unused slots. Each must clear a query-length-scaled term-coverage floor. The ranker favors partials that add terms earlier results missed. Exact technical text and phrases in titles, aliases, headings, or code fields return phrase matches only. A longer lexical miss can fall back to a close title or alias. Queries shorter than four characters do not use edit-distance suggestions.

Map search includes publish: false. Docs search covers the public manual. Both are local and omit queries from the logbook. Use discern map --search <query> or discern docs --search <query>, optionally after a target.

path and target answer different location questions. path chooses which project or worktree a project-operating MCP call uses. target chooses a region or document inside that project's map.

ok: true means every required outcome in the producing verb's completion policy holds. Required writes, validation, compilation, cleanup, and final checks cannot fail under a successful envelope. An explicitly optional degradation remains successful only when advisories[] carries its permitted kind, non-empty evidence, and next_action. Hints do not waive required work.

ok and the execution state form independent discriminated contracts. A failed gate run can carry diagnostics and completed steps beside its classified error. A required late failure can carry typed partial-effect data and recovery because ok: false does not imply rollback. A refusal can carry a review plan without claiming dry_run: true. Serialization omits undefined fields. Branch on ok, then verb, before reading data.

A failed JSON, Markdown, or MCP result always includes a registered next action. JSON and structuredContent carry it in hints; Markdown places it at the end of the presentation. Owner decisions occupy a separate Owner attention section before caller actions. When message or the first diagnostics entry explains the correction, the hint points there. When recovery depends on a choice or reported state, the hint names the relevant state and action. Consent, partial operations, incomplete setup, document lookup, and improvement thresholds use these specific instructions. A caller therefore does not have to infer whether to retry, review, choose, or complete cleanup.

setup begin checks the required setup permission before applying its plan. Ordinary acceptance checks permission separately for each landing. A result awaiting consent can still describe earlier tasks that already landed, so read its per-task outcomes before retrying. The result names the decision and continuation command. Dry runs need no permission because they only show the plan.

Setup consent is not write authority. Effectful commands probe plan-derived targets before mutation; denial returns write_denied, the exact path and retry, with phase unchanged. Read-only commands do not probe (Setup command boundaries).

Setup pages carry owner-facing semantic prose once. Compact spine.owner_moments projections preserve identity, kind, phase, purpose, recommendation, option ids, wait boundary, and relay protection. Compatibility fields derive from the same enrolled moments, so terminal, Markdown, JSON, and Model Context Protocol (MCP) share one authority without duplicating prose.

start, status, and green done results may carry data.landing_authority: authorized or conversation-required, with source, scopes, uncovered-path evidence, and warnings. Compact status and done results bound uncovered paths to six authored-first examples beside uncovered totals and scopes; start grants are prospective. An absent fact stays absent. See Landing authority.

status identifies the project in data.project. Its default structured projection retains the main fleet row and at most six non-main rows, selected by attention, current-checkout, recent-activity, and lexical priority. Every repeated collection is capped at six. fleet_total and positive projection.omitted counts preserve exact omissions under dotted paths with zero-based array indexes. Config refusals carry projection. Every sampled readable row carries one gate_proof, whose status is honored, report_only, missing, stale, dirty, unavailable, or read_failed. report_only is current for its commit but cannot authorize landing because checkpoint review was not enforced. An honored marker carries a compact proof with branch, trunk, validated commit, diff counts, and line. Rendered Proof pages and the earlier honored-only compatibility fields do not cross the structured-result boundary. Collision rows retain identities and shared-path counts. discern status --verbose --json and MCP verbose: true restore complete repeated collections and landing history with projection: { mode: "full" } and no omission map; terminal --verbose also holds collision paths and full Proof pages. See Status and session hints for the dashboard and projections.

Green means the required checks passed for the recorded commit; it does not mean the change landed. Later edits make Proof stale because the waiting code differs from what passed. Only you can approve an unmet checkpoint exception; a grant does not cover it.

For done, inspect data.completion as well as the top-level verdict:

Explicit CI reports use data.mode: "report" and report checkpoint review without answering questions. Their feedback does not provide landing Proof. checkpoint_drops preserves classified uncertainty about checkpoint enforcement.

discern_accept with action: "queue" returns the reviewed path, branch, head and complete proof pointer under data.revision. data.submission carries the observed authority; its state is planned for a dry run and queued after recording. A queued result includes submission_id and submitted_at; replaces, when present, names the previous queued commit. Queue mode accepts target, path and dry_run. It refuses landing consent, exception approvals and integration answers; use ordinary acceptance for those separate decisions. Apply rechecks the clean tree, current Proof and separate checkpoint or standard decisions. Repeating the same revision preserves its queue order. A later commit or done does not submit newer work. To start an acceptance walk, your agent uses discern_accept with target; queueing itself schedules no background run.

Ordinary acceptance returns data.queue — the landing queue, a derived view over submissions. Each row is one unlanded submission: pre-authorized rows come first in grant order, then rows awaiting-owner in submission order. discern status, the deskDesk↗An interactive view of the project's tasks and the actions available for them., and a dry_run: true preview show the same rows in the same order, and a dry run changes nothing.

After a landing, top-level fields carry the outcome. data.landing records the exact effects performed: the trunk transition and what happened to the worktree, branch, and resources. data.consent names the consent source, and data.root names the surviving checkout, including when acceptance removed the invoking worktree. data.proof_line is the final landing Proof line to relay verbatim; data.proof carries the pasteable landing record when available. data.variances and data.standard_approvals list what the landing carried, and checkpoint_drops preserves classified uncertainty about checkpoint enforcement. The published schema defines every optional field. See Recover an interrupted task for recovery.

An unlanded successful setup done carries Proof, canonical completion inventory, qualitative inventory.project_context, and landing state. It carries no reactivation or improvement advice. Project context includes the derived primary-subsystem handoff, project principles, and instruction sources. After successful setup accept, registry-derived data.reactivation carries each provider's exact check, local recovery, and command-line fallback. data.activation_context explains why a fresh session is necessary. data.optional_improvement remains conditional on activation verification. An in-place completion already on the trunk projects the same ordered activation contract.

setup done failures distinguish unfinished authoring, uncommitted paths, and exact owned rollback. Transactions name stage, rollback, retained state, next_action, and recovery; nested diagnostics keep location, rule, and reproduce command.

Applied setup and upgrade results carry data.instruction_refresh. status: "complete" means the required instruction refresh completed, even when compiled is empty because every artifact was current. status: "partial" makes top-level ok false and carries the completed artifacts, non-empty failure evidence, effects_preserved: true, and recovery: { command: "discern refresh", safe_to_retry: true }. The partial result reports prior scaffold or migrationMigration↗A numbered step that updates a project's discern configuration format. effects rather than pretending they rolled back.

Output metadata is advisory. A configured command's exit status decides the job verdict, except for standards. Their DISCERN_METRIC value is the measurement contract.

Gate and standalone standards results carry each standard's direction, limit, optional margin, measurement, value, and verdict. A measured or replayed value also carries the gate-owned pin_eligible decision and, when true, its exact pin_target. Those fields describe mechanical eligibility. Patterns applies the project-history decision rule.

Patterns results always carry data.investigations. Each entry cites source ids that remain present in data.findings, repeats their observations and denominators with numerical provenance, and states the shared evidence boundary, bounded interpretation, diagnostic action, and falsifier. An empty array means no registered relationship cleared its evidence requirements. Terminal, JSON, Model Context Protocol, and sealed-archive reads use the same synthesis arithmetic.

cancelled marks a fail-fast sibling and fails required completion. skipped marks a configured step that did not run. A policy can separately elect a user cancellation as successful no-effect completion.

Every diagnostic includes tool, severity, message, and reproduce_cmd. It may also include normalized output, truncated, output_path, file, line, col, rule, and fix_available. Use reproduce_cmd for the smallest direct rerun; use output_path when the inline capture was truncated.

The published schema marks every fixed-set result value with x-discern-vocabulary. An open vocabulary publishes as a string, with its known members at the schema root under the same key, and grows in ordinary releases: treat a value you do not recognize as opaque. A closed vocabulary publishes as an enum and changes only with that artifact's own major. The closed vocabularies are step outcome, diagnostic severity, validation mode, checkpoint mode, landing-authority kind, standard proposal direction, completion evidence purpose, requirement kind, and exception state; every other result vocabulary is open.

• Step kind (open): job, scope-gate, merge-check, standards-limits-check, tracked-artifacts-check, instructions-check, skills-check, tracked-refresh-check, resource-create, resource-destroy, git, task-metadata, setup-step, repository-ensure, checkout-clean-check, setup-ensure, env, refresh, tidy, standard.
• Step disposition (open): run, skip, gate.
• Step outcome (closed): ok, failed, skipped, cancelled.
• Diagnostic severity (closed): error, warning.
• failed_stage (open): fix, build, check, test, check/test, scope_gates, tree_drift, generated_drift, refresh_drift, tracked_artifacts, instructions, skills, skill_frontmatter, adr_numbers, adr_index, map_integrity, merge, standards, write_denied, validation_inputs.
• Advisory kind (open): acceptance-cleanup-incomplete, checkpoint-evidence-dropped, checkout-clean-observation-unavailable, doctor-warning, execution-cap-unavailable, generated-attribute-pattern-untranslated, governing-config-key-ignored, ignored-file-observation-unavailable, landing-authority-unverified, optional-resource-unavailable, proof-recording-unavailable, setup-unproven-completion, setup-machinery-commit-failed, setup-marker-commit-failed, standards-limits-unverified, uninstall-strip-incomplete.

The registered error slugs, published under x-discern-error-slugs, are: active_worktrees, ambiguous, apply_failed, awaiting_consent, awaiting_declaration, awaiting_standard_approval, awaiting_variance, below_min_score, brief_unparseable, checkout_failed, checkpoint_evidence_unavailable, config_template_unavailable, confirmation_required, conflict, desk_already_active, detached_head, diagrams_misaligned, dirty_worktree, edit_failed, gate_failed, gitignore_template_unavailable, identity_failed, incomplete, internal_error, invalid_arguments, invalid_config, invalid_config_file, invalid_migrated_config, invalid_settings_file, invalid_toml, invalid_value, no_docs, no_map, no_project, no_repository, no_trunk, not_main_checkout, not_on_setup_branch, not_on_trunk, partial_acceptance, partial_materialization, partial_refresh, pin_failed, precondition_failed, proposal_failed, proposal_stale, provisioned_resources, read_failed, renamed_command, renamed_config_key, report_only_proof, schema_version_too_new, script_not_a_command, script_not_executable, setup_plan_failed, setup_unfinished, skills_eject_failed, tables_malformed, templates_not_found, tidy_parse_failed, tidy_write_failed, unchanged_tree_rerun, unknown_category, unknown_command, unknown_key, unknown_standard, unknown_step, unknown_target, and write_denied.

{+target} accepts a slug, section/slug, or a path. Resource reads are computed when requested; clients that do not auto-attach resources can call the corresponding tool. The MCP tools manifest lists every resource and template by name, kind, and URI, and none of those change within the major.

Quiet result modes map exit 0 to evaluated ok: true and controlled nonzero to evaluated ok: false; a verb's manually reported zero cannot override a failed completion contract. Predicates using --json or --markdown always exit 0; their boolean is in data. Bare config has and impact --has stay silent, exiting 0 or 1. identity and config reads are bare unless --json or --markdown requests a result.

types/discern-json.d.ts in the matching release source archive provides release-pinned standalone TypeScript types indexed by verb, command path, and MCP tool name. Each per-verb type intersects with DiscernResultState, so narrowing ok also narrows error, and planned and completed steps cannot coexist. The result schema's x-discern-contracts metadata publishes each registered verb's completion_policy, including required_postconditions, optional_advisories, refusal, cancellation, partial-effect, no-op, and recovery-owner policy.

The compatibility page explains what each published contract promises across releases: the schema majors, the evolving tier, the open and closed vocabularies, and the deprecation rule. This page keeps the result-shape facts that page does not carry.

data.instruction_refresh.status: "partial" means a required refresh failed even when earlier setup or upgrade effects remain. A successful setup accept with nothing to land carries data.completion = { status: "no_op", reason }; reason distinguishes no_git_repository from already_on_target.

Schemas use JSON Schema Draft 2020-12. The release source contains types/discern-json.d.ts, and the result schema publishes x-discern-contracts metadata for each verb's completion requirements and permitted advisories. Use these artifacts from the release you integrate with.