generate_handoff

EXECUTOR SESSIONS: MANDATORY - call at end of every session before disconnect. Never write markdown manually. Read-only: Generate a context handoff. mode='full' writes the complete L0/L1/L2 handoff; mode='delta' returns a compact session update (completed + pending + /goal); mode='starter' returns a <=20-line block for paste-after-/compact or cold start - project_id, start_session command, last 5 completed titles, top 3 pending IDs, /goal; mode='planner' returns strategic context for a claude.ai planning chat; mode='goal' (682005f4) returns ONLY the bare /goal block itself - no readiness header, no workspace decisions/notes, no L0/L1/L2 context - with each pending item's resolved code pointer(s), if any, rendered inline in <sprint_items>. FORWARD THE RETURNED content FIELD VERBATIM to the user (a5e8aa74) - the server delivers content as the EXACT raw handoff text, with NO Markdown code fence, header, or blockquote added around it (earlier versions wrapped it in a 4-backtick fence under 5234877f; that wrapping was removed because it broke copy-paste fidelity for the /goal trust protocol - see format_handoff_mcp_content in meridian/handoff.py). Output the field value as-is, as the sole plain-text bubble - do NOT add your own fence, header, blockquote, or any other wrapping on the calling side either. Do NOT just narrate that the handoff succeeded; paste the actual text. Also returns capability_contract (98aaccf4) on every mode: a machine-readable {requested, effective, availability, manifest_hash, executable, executable_reasons, generated_at} object describing the project's declared capabilities and whether an executor can run right now — null if contract-building failed. Every executor-facing /goal payload also includes an explicit <executor_item_ids> manifest containing every claimable item ID in deterministic order; receivers must use that manifest rather than parsing presentation prose or a truncated starter preview. Also returns scope (b8f89491) on every mode: {requested_version, effective_version, session_id} — which sprint-version bucket the handoff actually resolved to (explicit version arg wins over the session's own stored sprint_version; both null means genuinely unscoped, every version). Every mode's /goal text (full/delta/starter/goal, embedded in content or returned bare) also carries a structured <execution_policy execution_mode=... max_planning_turns=... required_first_action=... no_confirmation=... permitted_parallel_wave=... claim_before_edit=...> tag (75ac1c8e) right after <executor_directive> — the SAME canonical policy start_session's execution_policy field returns, so a receiver can identify the required first action from the tag attributes without interpreting prose. Also returns handoff_evidence_status (8a883f60) on every mode: an explicit {code_pointer_enrichment, resolved_pointer_annotation, freshness_requery, wave_gate_exclusion, graph_search_availability} object — each a {status: verified|skipped|failed|degraded, reason, fallback} entry for that best-effort step, so a silently-degraded handoff is never indistinguishable from a fully-verified one. Pass strict_evidence=true to fail CLOSED instead: if any capability comes back failed/degraded, nothing is rendered or persisted and the call returns {error: HANDOFF_EVIDENCE_BLOCKED, evidence_status, evidence_errors, message} — default (strict_evidence omitted/false) behavior is completely unchanged. Also returns continuation_status (ecc8b280) for full/delta modes: a {continuation_required, terminal_ready, execution_mode, actionable_count, actionable_pending_count, actionable_in_progress_count, actionable_item_ids, blocked_count, blocked_item_ids, reason} object reporting whether actionable pending/in_progress work remains on the live, version-scoped board with no recorded blocker_kind, while execution_mode=autonomous — the machine-readable signal that an autonomous session may NOT yet treat itself as finished. Pass checkpoint=true when THIS call is a mid-run progress report, not a final session-ending handoff — a checkpoint is never blocked by the gate below. Pass strict_continuation=true to fail CLOSED instead of just reporting: if continuation_required is true and checkpoint is not set, nothing is rendered or persisted and the call returns {error: HANDOFF_CONTINUATION_BLOCKED, continuation_status, message} — resolve/claim the remaining item(s), record a genuine blocker_kind on them, or call again with checkpoint=true. Default (strict_continuation omitted/false) behavior never blocks — continuation_status is still always returned so a caller can act on it voluntarily. Also supports selected_item_ids (cffb9323) — an explicit INCLUDE-ONLY item scope for safe parallel-follow-up handoffs. force_include_ids only ever WIDENS the pending list (re-adds specific deferred ids); selected_item_ids NARROWS it: when given, generate_handoff resolves a dependency-closed scope (the requested ids plus any transitively-required depends_on ancestor still todo/pending) and applies it identically across every executable mode (full/delta/starter/goal), so an isolated two-item follow-up handoff never emits the rest of the eligible version backlog or overlaps an active wave/batch a sibling session already owns. The rendered /goal carries a <selected_item_scope requested=... closure=... closure_hash=...> tag stating the exact selected ids and the wave plan — embedded in the body BEFORE the provenance token is minted, so the selection is bound into the SAME body-hash/token-integrity mechanism (efaa918a) as the rest of the /goal block. Fails CLOSED, not silently widened: a missing/foreign/wrong-version/already-in_progress/otherwise-non-pending requested id raises a structured refusal (error=HANDOFF_SELECTION_BLOCKED, selection_rejected) — nothing is rendered or persisted for that call. (7a373f41) A selection that validates cleanly but collapses to zero executable items once the manual/backburner/unprospected/wave-gate exclusion filters run instead refuses with error=HANDOFF_SCOPE_NON_EXECUTABLE, requested_ids, and an excluded_requested reason list — this same contract is identical across every connector surface (hosted HTTP MCP, stdio, and the REST /handoff route). Persistent-state disclosure: on hosted Meridian, supplied text and project/session metadata are sent to and stored in Meridian's service; self-hosted deployments keep them in the configured local SQLite/Postgres database. This data is visible in the dashboard/API and later project context or handoffs. Delete individual tasks, notes, or decisions where supported, or delete the project/account using the documented controls. Do not include secrets. It is categorised as a Write tool in the Meridian MCP Server, which means it can create or modify data. Consider rate limits to prevent runaway writes.

generate_handoff accepts 12 parameters: mode, version, root_dir, checkpoint, project_id, session_id, project_name, skip_ai_summary, strict_evidence, force_include_ids, selected_item_ids, strict_continuation. The full parameter table on this page comes from the server's own tool schema.

Register the Meridian MCP server in PolicyLayer and add a rule for generate_handoff: allow, deny, rate-limit, or require approval. Point your MCP client at the PolicyLayer proxy URL and the rule is enforced on every call, before it reaches Meridian. Nothing to install.

generate_handoff is a Write tool with medium risk. Write tools should be rate-limited to prevent accidental bulk modifications.

Yes. Add a rate_limit block to the generate_handoff rule in your PolicyLayer policy. For example, setting max: 10 and window: 60 limits the tool to 10 calls per minute. Rate limits are tracked per agent session and reset automatically.

Set action: deny in the PolicyLayer policy for generate_handoff. The AI agent will receive a policy violation error and cannot call the tool. You can also include a reason field to explain why the tool is blocked.

generate_handoff is provided by the Meridian MCP server (@meridianmcp/mcp). PolicyLayer sits as a proxy in front of this server to enforce policies before tool calls reach the server.