Create a new campaign for long-running, multi-step work.

Args: goal: What this campaign should accomplish. name: Short name for display. Auto-generated if omitted. channel: Discord channel for notifications. priority: urgent / high / normal / low / background. max_depth: Max nesting depth for subtasks (default 4). token_budget: Optional token limit. NULL = unlimited. dry_run: If true, create in paused status for review. success_metric: Short metric name emitted by the verifier / benchmark (e.g. "accuracy_at_1k"). Paired with benchmark_command. Leave NULL for free-form campaigns. benchmark_command: Shell / Python invocation that produces a JSON line with the metric value. Metadata only — the runner does not execute it; worker steps do. scope: Freeform identifier narrowing the benchmark (e.g. "chapter-01", "test_subset_A"). max_iterations: Hard cap on autoresearch-style loops. NULL means open-ended (planner decides).

Returns: Campaign ID, name, status, next_action_at.

Next: Use get_campaign(id) to check progress, or steer_campaign(id, guidance) to adjust.

List campaigns, optionally filtered by status.

Args: status: Filter by status (active/paused/done/failed/cancelled). Omit for all.

Returns: Array of {id, name, status, priority, progress}.

Get full campaign state: goal, strategy, progress, step tree, recent notes.

Sets last_reported_at so next call only returns new activity.

Args: id: Campaign UUID.

Returns: Full campaign state with steps and recent notes.

Get delta since last report: completed steps, failures, new notes.

Args: id: Campaign UUID. Omit for updates across all active campaigns.

Returns: Recent completions, failures, and notes.

Change campaign direction. Updates strategy for the planner.

Args: id: Campaign UUID. guidance: New direction, constraints, or focus areas.

Returns: Updated strategy.

Pause a campaign. Running steps finish but no new ones start.

Args: id: Campaign UUID.

Resume a paused campaign.

Args: id: Campaign UUID.

Provide input to a step that is waiting for a human decision.

Workers call request_input when they need guidance. This tool unblocks them by supplying the answer and returning the step to the ready queue.

Args: id: Campaign UUID. step_id: The step waiting for input. answer: Your decision / the information the agent asked for.

Returns: Updated step status.

Evaluate whether a campaign has met its typed success contract.

A campaign's success contract (success_metric, benchmark_command, scope, max_iterations) is set at creation time by templates like autoresearch. This tool gives the planner / coordinator a single scalar decision:

• met=True — contract satisfied; coordinator should mark the campaign done.

• met=False — keep iterating, or escalate if budget exhausted.

• iterations_used — count of DONE atomic steps on this campaign so far. Useful for comparing against max_iterations.

• metric_value — the most recently recorded metric from campaign_notes tagged metric:<success_metric> (best-effort parse; see below).

How the metric is discovered. The runner / worker agents emit a note of the form::

add_note(campaign_id, f"metric={value}", tags=["metric:<name>"])

on every benchmark run. check_success scans the most recent such note, extracts the float after =, and compares it against success_metric_threshold if set via steer_campaign(strategy=...). In v0.3 we only surface the most-recent value — the planner decides whether it's "good enough". A future revision may wire a numeric threshold column.

Args: id: Campaign UUID.

Returns: {met, metric_value, iterations_used, max_iterations, success_metric, notes_checked, reason}

``reason`` is a short string explaining the decision — useful
both for humans looking at logs and for the planner's own
chain-of-thought.

A campaign without a success contract returns {met: False, reason: "no_success_metric_configured"}.

Next: if met is True, call cancel_campaign(id) or steer_campaign(id, "wrap up"). If False and iterations_used >= max_iterations, escalate via the notification channel.

Cancel a campaign. All pending steps are skipped.

Args: id: Campaign UUID.

Get campaign context for the step you're executing.

Upstream outputs are returned as previews (head + tail + total char count) so the context bundle stays small. Call read_step_output(<id>) when you need the full body of a specific upstream output.

Args: step_id: Your step ID. Inferred from $SORTIE_STEP_ID if unset.

Returns: Campaign goal, your task, upstream output previews, notes.

Next: Do your work, then call complete_step(summary) or fail_step(error).

Read a range from a step's output (or input) field.

Counterpart to the preview-plus-seek contract in get_my_context: when an upstream preview is truncated, call this with the step_id from the preview to pull the full (or a slice of) text.

Args: step_id: The step whose output you want to read. Does not have to be your own step — any step in the same campaign's DAG is readable. offset: 0-indexed character offset to start from. limit: Max characters to return (default 8000, capped at 32000 to avoid blowing the agent's context). field: "output" (default) or "input".

Returns::

{
    "step_id": N,
    "field": "output",
    "content": "...",
    "offset": 0,
    "limit": 8000,
    "total_chars": N,
    "has_more": bool,  # True if offset+limit < total_chars
}

Report that you're still alive and keep your claim + leases fresh.

Long-running agents should call this every few minutes. The runner's reset_zombies sweep uses heartbeat_at to distinguish healthy workers from crashed ones. If you hold resource leases (see requires_locks on your step), the lease expires_at is bumped by extend_leases_sec from now so the lease reaper won't steal them out from under you.

Returns {"status": "stale_claim"} if your claim token no longer matches — this means the zombie reset already repossessed your step. Stop working immediately if you see that: another runner is about to pick your step up.

Args: step_id: Your step ID. Inferred from $SORTIE_STEP_ID if unset. extend_leases_sec: Seconds of TTL to give every lease you hold. Default 900 (15 min). Set to 0 for heartbeat-only.

Returns: {"status": "ok" | "stale_claim", "step_id": N}.

Record a noteworthy finding during step execution.

Notes are embedded for semantic search across the campaign.

Args: campaign_id: Campaign UUID. content: What you found. Be specific. tags: Optional tags for filtering (e.g. ["finding", "citation"]).

Returns: Note ID and any similar existing notes.

Next: Continue your work. Call complete_step when done.

Semantic search across campaign notes.

Args: query: What to search for. campaign_id: Scope to a specific campaign. Omit for all. top_k: Number of results (default 5).

Returns: Ranked results with content and tags. Each entry is annotated with "mode": "semantic" when cosine ranking was used, or "mode": "recency" when embeddings were disabled / unavailable and the server fell back to most-recent-first listing.

List notes filtered by tag or step.

Args: campaign_id: Campaign UUID. tags: Filter by tags (OR match). step_id: Filter by step ID.

Returns: Matching notes.

Mark your step as done with a summary of what you accomplished.

Args: step_id: Your step ID. Inferred from $SORTIE_STEP_ID if unset. summary: What you did and what you found. This becomes the step output visible to downstream steps.

Returns: Confirmation. If the step was already skipped (branch abort), returns {status: "skipped"} — your output is recorded for audit. Returns {status: "stale_claim"} if a zombie-reset already stole your claim — stop working.

Report that you cannot complete your step.

Args: step_id: Your step ID. Inferred from $SORTIE_STEP_ID if unset. error: What went wrong and why you can't continue.

Returns: Whether the step can be retried or has failed permanently.

Pause your step and ask the coordinator for a decision.

Use when you hit a fork that requires human judgement — e.g. which approach to take, whether to proceed with a risky action, or clarification on ambiguous requirements.

Your step pauses until the coordinator calls provide_input. When it resumes, the answer will be in your step's input field (visible via get_my_context).

Args: step_id: Your step ID. Inferred from $SORTIE_STEP_ID if unset. question: What you need decided. Be specific. partial_output: Optional summary of work done so far.

Returns: Confirmation that the step is paused.

Split your work: spawn subtasks and a continuation that resumes after they complete.

Use when you discover you need additional work done before you can finish. The DAG rewires automatically — your downstream dependents will wait for the continuation, not your partial result.

Args: step_id: Your step ID. partial_output: What you've done so far. subtasks: List of {action, agent?} dicts for work that needs doing. continuation: Action description for the step that resumes your work after subtasks complete.

Returns: IDs of created subtasks and the continuation step.

Note: This tool is hidden at max depth — you must complete atomically.

Early return from an ancestor step, skipping the rest of its branch.

Use when you discover that an entire branch of reasoning is pointless — not just your step, but the ancestor that initiated it.

The target step completes with your output (it doesn't fail). The target's parent (the requestor) sees the result and decides what to do next.

Args: target_id: The ancestor step to return from. output: The result for the target step (e.g. "Approach debunked by X"). reason: Why this branch is untenable. Saved as a campaign note. step_id: Your step ID. Inferred from session if omitted.

Returns: List of skipped step IDs.