start_session
Register a session and return orientation. Compact by default (session_id, sprint focus + status counts, 3 recent tasks, board_change count) to keep an executor's context small. Pass compact=false for the full block (goal XML, decisions, MERIDIAN.md instructions, workspace context, sprint items) ...
This record as markdown: /tools/io-github-ajc3xc-meridian/start-session.md
What start_session does on Meridian
AI agents invoke start_session to trigger actions in Meridian. What it does depends on the arguments the agent supplies, and its effects often reach beyond the immediate call: builds kicked off, notifications sent, workflows started.
| Parameter | Type | Required | Description |
|---|---|---|---|
cwd | string | — | W1-G (G1/G2) — optional: this session's local working directory. When this project has never seen a cwd before, the FIRST one reported becomes its canonical rep |
mode | string | — | Pass 'continue' to resume an already-active same-name session WITHOUT re-reading the full L0/L1/L2 orientation: returns just session_id + live pending items + t |
role | string | — | 325276f8 — 'executor' injects executor_config and credentials guidance and narrows active_tool_set to executor-oriented tools; 'planner' narrows active_tool_set |
client | string | — | |
compact | boolean | — | Default true — slim orientation. Set false for the full goal/instructions payload. |
version | string | — | Optional sprint-version bucket (e.g. 'v0.1.x') to scope this session to. Sprint progress/items in the orientation and /goal filter to it. Omit to auto-infer the |
human_id | string | — | |
project_id | string | — | |
project_name | string | — | Project name — an alternative to project_id; resolved to the id internally. project_id wins if both are given. |
session_name | string | — | Optional (599d0097): omit or leave blank to auto-generate a meaningful name from the first pending sprint item title + a timestamp, instead of inventing a strin |
Parameters from the server's own tool schema.
Why start_session is rated High
start_session triggers real processes with real consequences. An agent gone sideways doesn't fire it once. It starts dozens of builds, sends mass notifications, or burns through compute before anyone looks up.
Risk signalsAccepts file system path (cwd) · High parameter count (10 properties)
Attacks that exploit this kind of access
The rule that runs start_session safely
PolicyLayer is an MCP gateway: it sits between your AI agents and Meridian, and checks every tool call against a rule you set before the call runs. Nothing changes on the server itself. For start_session, this is the rule to start with:
start_session stays usable, but rate-capped: a runaway agent can't fire it dozens of times a minute. Everything else on the server is denied unless you say otherwise.
The button opens the PolicyLayer dashboard: create your workspace, connect Meridian, apply this rule, and every start_session call is checked against it from then on.
Questions about start_session
Register a session and return orientation. Compact by default (session_id, sprint focus + status counts, 3 recent tasks, board_change count) to keep an executor's context small. Pass compact=false for the full block (goal XML, decisions, MERIDIAN.md instructions, workspace context, sprint items) — or fetch it later with get_session_brief. Pass version to scope the session to one sprint-version bucket (e.g. 'v0.1.x'): the orientation's sprint counts/items filter to it and the scope is remembered for the /goal template. Omit version to auto-scope to the bucket with the most pending items (empty board → unscoped). Also returns capability_contract (98aaccf4): 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. Also returns execution_policy (75ac1c8e): a machine-readable {execution_mode, max_planning_turns, required_first_action, no_confirmation, permitted_parallel_wave, claim_before_edit, genuine_blocker_escalation} object — 'immediate' (default) names the exact first tool call to make and bounds planning turns before it; 'relaxed' is the explicit ask-first/planning posture. Derived from the project's execution_mode; max_planning_turns is executor_config-overridable via set_executor_config. Persistent-state disclosure: on hosted Meridian, supplied text and project/session metadata -- including task log entries, pinned decisions, sprint items, notes, handoff/goal state, and HITL queue items -- are sent to and stored in Meridian's service, in an isolated per-tenant Postgres database (Neon); self-hosted deployments keep the same categories in the configured local SQLite/Postgres database. This data is visible in the dashboard and API, and may resurface in later project context or handoffs. Notes and pinned decisions can be deleted individually; task log entries and sprint items can be deleted via the dashboard/API (not exposed as an agent-facing tool); HITL queue items and handoff state have no per-record delete. Full removal of any of this data is available via project or account deletion, using the documented controls. Do not include secrets. It is categorised as a Execute tool in the Meridian MCP Server, which means it can trigger actions or run processes. Use rate limits and argument validation.
start_session accepts 10 parameters: cwd, mode, role, client, compact, version, human_id, project_id, project_name, session_name. 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 start_session: 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.
start_session is a Execute tool with high risk. Execute tools should be rate-limited and have argument validation enabled.
Yes. Add a rate_limit block to the start_session 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 start_session. 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.
start_session 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.
More on Meridian, and thousands of servers like it.
Across the catalogue