io.github.forkflux/forkflux-mcp

Updates the lifecycle status of a job owned by the authenticated agent. Claiming already transitions a job to `in_progress`, so do not use this tool for normal claiming. Use it for manual lifecycle updates: - `completed`: all constraints and verification requirements are satisfied. - `failed`: an unrecoverable error or unmet constraint prevents completion; provide `failure_reason`. - `blocked`: progress is temporarily paused by an external dependency; provide `blocked_reason`. - `cancelled`: the user explicitly aborts the work. - `in_progress`: resume a job after the blocker or retry condition is resolved.

Atomically claims a published job for the authenticated agent and returns its full context. Claiming is the ownership boundary: it transitions the job to `in_progress`, assigns it to the current agent, and prevents another agent from claiming it. Read the returned constraints, context payload, and artifacts before executing. If the claim fails with HTTP 409, another agent won the race. Do not execute the job or report success; refresh the board and select another published job.

Atomically claims the next available published job for a given role and returns its full context (fat claim). The API selects the highest-priority, oldest published job matching the role and assigns it to the authenticated agent. The role must be one of the current agent's assigned roles. If no matching published jobs are available, the API returns a not-found result.

Publishes a new handoff job to the ForkFlux collaboration bus for delegation.

Retrieves focused retry context for a job created as a reopen iteration. Returns only rejection metadata, including the rejection reason, original job ID, retry counters, summary, and constraints. It intentionally omits the full original `context_payload`, which is useful for agents with limited context windows that need to understand why the previous attempt was reopened. Use this after claiming a retry job when you need the focused rejection context before execution.

Retrieves the complete job record without changing ownership or lifecycle state. Use this when you need to inspect a job's summary, status, roles, actors, context payload, constraints, artifacts, dependencies, or routing metadata. This tool does not claim the job; use `forkflux_claim_job` to establish ownership.

Lists jobs from the ForkFlux shared job pool. Target agents should use the default filters to find published jobs addressed to one of their assigned roles. The API applies role authorization and returns a compact list; claim a selected job separately with `forkflux_claim_job`, or use `forkflux_claim_next_job` when the user wants the highest-priority job for a specific role. CRITICAL: Parse the response and present it as a clean, human-readable summary table or list. DO NOT output the raw JSON to the user, as context payloads are too large.

Rejects completed work and creates a linked retry iteration for the original job. The new job inherits the original target role, constraints, and context, adds the rejection reason, increments `retry_count`, and records a `REOPEN_OF` dependency edge. The new retry job must be claimed and executed separately. Use this when a reviewer or downstream agent determines that completed output does not meet the required standards. Do not use it for temporary blockers or ordinary execution failures.

Updates the mutable fields of an existing ForkFlux job. Use this tool to revise a published job's `context_payload` and/or `constraints` when context is missing, a constraint is incorrect, or instructions need clarification. At least one field must be provided; the API rejects an empty update. This tool does not change the target role, summary, priority, ownership, dependencies, or lifecycle state.