Skip to main content
Glama
Sign In
zai-one

grok-delegate

by zai-one
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Delegate (background)

grok_delegate_start

Start long-running coding lanes in the background, returning a job_id at once so client timeouts don't kill the run. Poll with grok_delegate_poll.

Instructions

Start grok_delegate in the BACKGROUND and return a job_id immediately. Use this instead of grok_delegate for real lanes: a lane runs for minutes and a synchronous call is killed by the client timeout, leaving an empty worktree. Poll with grok_delegate_poll. Same guarded profile, no push, no merge.

Input Schema

NameRequiredDescriptionDefault
cwdNoProject directory to work in; must be an allowlisted root
goalYesCoding goal for the executor
laneYesLane slug or grok/<slug> (not dev/master/main)
modelNoOptional model id
rulesNoOptional extra rules appended to system prompt (bounded)
resumeNoResume session: true for most recent, or a session UUID string
sandboxNoOptional sandbox profile override: off|workspace|devbox|read-only|strict (known built-ins only)
base_refNoGit base ref (default origin/dev)origin/dev
max_turnsNoMax agent turns (server hard-capped at 60)
plan_onlyNoIf true, use read-only permission profile
repo_rootNoAbsolute path to a repo root; accepted only if it resolve()s to an entry on GROK_DELEGATE_ALLOWED_ROOTS (or single GROK_DELEGATE_REPO_ROOT pin)
session_idNoUUID for --session-id (new or forked session name)
json_schemaNoOptional JSON Schema object/string for structured output
fork_sessionNoPass --fork-session (requires resume/continue)
lane_verdictNoAttach the lane verdict schema (default true). The run ends when the executor emits that object, so on a goal it must read the codebase to start, it emits one describing intent and the lane closes empty. Set false for exploration-heavy goals: the executor then works to natural completion and reports prose in summary instead of a parsed verdict.
lanes_parentNoOptional parent dir for worktrees; rejected if inside repo_root or outside GROK_DELEGATE_LANES_PARENT when that env is set
no_subagentsNoIf true, pass --no-subagents
continue_sessionNoPass --continue (most recent for cwd)
reasoning_effortNoOptional reasoning effort (low|medium|high|…)
disable_web_searchNoIf true, pass --disable-web-search

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.26.1
    • addedInput schema / properties / cwd
      Added value: +{
+  "description": "Project directory to work in; must be an allowlisted root",
+  "type": "string"
+}
  2. First observedv0.4.1

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare non-read-only, open-world, non-idempotent, non-destructive, but the description adds the concrete workflow consequence: an immediate job_id return, polling requirement, and the safety posture 'Same guarded profile, no push, no merge'. It notably warns that the sync path can leave an empty worktree, which annotations alone would not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core behavior and the job_id return, then the routing rationale, then the polling follow-up. No filler; every clause carries operational information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 20-param background job tool with no output schema, the description covers the return value (job_id), the reason to prefer it, and the next step. It omits what happens on job failure, timeout, or expiry, which would help an agent recovering from an unsuccessful run.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across all 20 parameters, so the schema already carries the param semantics (cwd allowlist, lane slug restrictions, lane_verdict behavior, sandbox profiles). The description adds no parameter-level detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (start) plus the resource (grok_delegate) and the exact mode (BACKGROUND), and explicitly names the sibling it replaces (grok_delegate). An agent can distinguish it from the synchronous variant without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use rule ('for real lanes: a lane runs for minutes'), explains the failure mode of the alternative ('a synchronous call is killed by the client timeout, leaving an empty worktree'), and names the follow-up tool (grok_delegate_poll). Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools