Tasks

---
name: tasks
slug: tasks
owner: pioneer
description: "Use this skill when Pioneer should create, inspect, update, reschedule, pause, resume, troubleshoot, or configure delivery for durable tasks, scheduled tasks, recurring tasks, interval tasks, cron jobs, background work, or existing task state."
version: "0.1.0"
user-invocable: true
disable-model-invocation: false
implicit-invocation: required
catalog-hide: true
---

# Pioneer Durable Tasks

Durable tasks are product objects that can outlive the current turn. They have task state, run history, result snapshots, attempts, diagnostics, schedules, and delivery behavior.

When observing a task with `task_get`, distinguish task, run, and execution status. A `running` run is unfinished; no result or unchanged `updatedAt` does not prove a stall. The execution heartbeat is periodic liveness, while `lastActivityAt` is confirmed activity only when recorded. Missing activity is unknown. Do not cancel or repeat work solely because it is taking time or repeated observations are unchanged. A `task_wait` timeout ends only that wait window and permits another wait for active attached work.

Use this skill for future, recurring, background, or already-existing task work. For attached child agents created to help with the current turn, read `system:pioneer/subagents` instead.

## Product Model

Think in three surfaces:

- **Task state**: durable source of truth for what should run, what did run, results, attempts, errors, and diagnostics.
- **Run execution**: a concrete attempt to perform the task now or later.
- **Delivery**: the policy that decides whether a terminal task result becomes a thread message, user notification, webhook call, or no visible output.

Do not confuse "the task produced a result" with "the user saw the result in this thread." Execution and delivery are separate.

## Quick Start

Before using durable task tools, decide what kind of task work this is.

1. If work should run later or repeatedly, use `task_create` to create a scheduled, interval, or cron task with self-contained future-run instructions.
2. If existing task behavior must change, inspect it first with `task_get` or `task_list`.
3. If only the schedule changes, use `task_reschedule` when available.
4. If delivery changes, patch only delivery and verify it.
5. If the task should be temporarily stopped or restarted, use pause/resume tools when visible.
6. If a result should appear in this chat later, configure thread delivery deliberately.
7. If the result should only alert the user, use notification delivery only when a durable chat message is not required.

For future scheduled work, do not call `task_wait` after creation unless an active waitable run exists. Confirm the task id, schedule, timezone, delivery behavior, and where results will appear.

## Load References When Needed

Keep this file in context for normal durable task work. Load detailed references only for the matching situation:

- Read `references/tool-schemas.md` before constructing non-trivial durable task payloads, after schema errors, or when exact field names matter.
- Read `references/delivery-and-scheduled.md` before creating or updating scheduled/interval/cron tasks, changing delivery, choosing notification vs thread delivery, or diagnosing why a result did not appear in the main thread.
- Read `references/troubleshooting.md` after task tool failures, missing final answers, hidden results, noisy recurring messages, delivery confusion, or stuck/stale tasks.

For current-turn attached child agents, read `system:pioneer/subagents`.

## Tool Visibility

Only call task tools that are visible in the current turn.

If a needed task tool is hidden and `request_tools` is visible, request the task domain:

```json
{
  "domains": ["task"],
  "reason": "Need task tools to create, inspect, update, reschedule, pause, resume, or troubleshoot durable task work."
}
```

Do not request individual task tool names. Request the `task` domain.

The `task` domain also exposes `threads_start_options`; opening `threads` separately is unnecessary to inspect task launch options. Call it when you need to choose an identity, execution profile, or permitted destination explicitly. For a task that inherits the parent's identity and profile in the current execution, omit `launch` and `targetOptionId`; no preliminary options call is required. Options do not grant permission to create or run a task. See `references/tool-schemas.md` for the exact fields.

If the task domain cannot be opened, do not pretend the task was created, updated, rescheduled, paused, resumed, or inspected.

## Creating Durable Future Work

Scheduled task instructions must be self-contained because future runs may not have the current chat context, exact tool list, skills, MCP servers, or web state.

Good scheduled instructions:

- say what to do step by step;
- include target URLs, repos, paths, ids, dates, and timezones;
- say how to choose tools by capability;
- define no-op behavior;
- define failure behavior;
- define output language and format;
- avoid relying on hidden parent reasoning.

Bad scheduled instructions:

```text
Do the same as above every day.
Use the tool I just used.
Keep track of it and continue.
Send it to me.
```

## Delivery Rules

The initiating thread is the original user-facing conversation. The execution thread is where the agent runs and may be an internal child. Choose delivery by the intended recipient, not by the execution location.

Use delivery to match the user experience:

- `thread` + `origin_thread`: deliver to the initiating conversation, without supplying `threadId`.
- `thread` + `current_thread`: deliver to the current execution thread, without supplying `threadId`.
- `thread` + `collaboration_root`: deliver to the root conversation of the collaboration capsule, without supplying `threadId`.
- `thread` + `exact_thread`: write the result to an explicitly supplied `threadId`.
- `user_notification`: notify the user without necessarily writing a durable chat message. Good for lightweight alerts, but bad when the user expects the full answer in the main thread.
- `webhook`: send the result outside Pioneer.
- `none`: keep the result in task state only.

Changing delivery affects future runs. It does not retroactively materialize already delivered results in the parent thread.

## Updating Existing Tasks

Task access belongs to the authorized root-thread capsule, not to the turn/run or hidden execution thread that created the task. A later authorized execution in the same capsule can inspect and manage the existing task by its stable `taskId`, within both its admitted action grants and the initiating user's current permissions. A user's broader rights do not widen an execution's restricted grants. Knowing an id does not grant access to another capsule.

`task_access_denied` means this execution cannot perform the operation; it does not mean the task is absent, broken, cancelled, or no longer scheduled. Do not create a replacement merely because inspection or cancellation failed: the original schedule may still fire. Report the blocker and possible duplicate risk. For `task_state_conflict`, reload the task and reconcile the requested change. For `task_operation_failed` (or older `agent_runtime_integrity_lost`), report an unconfirmed operation, not a dead task.

Use `task_list` or `task_get` to inspect before patching. Patch only fields that should change.

For delivery fixes, preserve schedule, goal, instructions, and output instructions unless the user asked to change them.

For prompt changes on scheduled tasks, ensure `instructions` and `outputInstructions` remain self-contained for future runs.

After an update, verify the current task state with the tool result or `task_get`. Tell the user exactly what changed and what will happen on the next run.

## Before Finalizing

Validate task state before answering:

- task id is known;
- schedule/timezone/next fire time are known or explicitly unavailable;
- delivery destination is known;
- no-op visibility is clear when relevant;
- updated fields were verified;
- the user understands whether changes affect past runs or only future runs.

Do not invent a run result for a scheduled task that has not run yet.

## Gotchas

- Scheduled tasks are not attached subagents.
- Do not call `task_wait` for scheduled future work with `waitable:false` or `runId:null`.
- `user_notification` does not guarantee a durable thread message.
- `includeResult:false` can produce only a generic delivery message.
- Delivery changes affect future runs, not past runs.
- Scheduled task instructions must be self-contained.
- Do not claim a task was created, updated, paused, resumed, rescheduled, or delivered unless the relevant tool succeeded.