pi-tasks

Pi-native execution contracts for AI agents — no more "trust me, it's done."

Why pi-tasks?

AI coding agents say "done" without proof. Context compaction loses progress. Multi-step work drifts without anyone noticing. You end up asking "what's the status?" over and over.

pi-tasks gives your Pi agent a binding execution contract: structured plans, evidence gates, ordered execution, and compaction-safe resume — all visible in your TUI.

What makes it different

Every other task tool for AI agents is just a todo list. pi-tasks enforces three hard contracts no competitor offers:

Plus: ordered step execution, scope drift detection, weak-model recovery guidance, decision/blocker audit trails, and branch-aware persistence.

Competitive landscape

Different tools solve different parts of the agentic workflow. Pick based on what matters most to your team:

pi-tasks is for you if your core problem is agents claiming "done" without proof, plans drifting mid-execution, or context compaction losing progress. If you need workflow orchestration or multi-agent coordination, the tools above may be a better fit — or complement pi-tasks.

Install

pi install npm:pi-tasks

For Oh My Pi (omp):

omp install pi-tasks

Equivalent explicit plugin command:

omp plugin install pi-tasks

Oh My Pi's --scope project flag is for marketplace refs such as name@marketplace; it is ignored for npm package specs like pi-tasks.

For local development:

pi install ./
omp plugin install ./

How it works

task_plan → ordered steps with acceptance criteria
    ↓
task_focus → agent sees exactly what's in scope
    ↓
task_update → step-by-step execution with evidence lock
    ↓
task_evidence → attach proof before marking done
    ↓
task_complete → only succeeds when all gates pass

Fresh sessions expose only task_plan and task_resume; after a persisted task is created or restored, pi-tasks activates the available task controls. Explicit Pi tool allowlists, exclusions, and noTools remain ceilings, and unrelated active tools are preserved. The user gets /tasks. Everything persists in Pi's session tree.

Oh My Pi support

Oh My Pi discovers extension packages through the same manifest shape:

{
  "pi": {
    "extensions": ["./dist/index.js"]
  }
}

No separate omp manifest is required. pi-tasks uses the Pi-native APIs that Oh My Pi exposes: registerTool, registerCommand, appendEntry, ctx.sessionManager.getBranch(), ctx.ui.setStatus, ctx.ui.setWidget, and the session_start, session_tree, and session_before_compact lifecycle events.

Because Oh My Pi renders model-facing tool guidance from description and parameters, the initial task_plan and task_resume entrypoints mirror their critical guidance into descriptions. Lazily activated controls keep only compact descriptions so native Pi can add them without active-only prompt metadata.

Native semantic assessment

task_plan, task_decompose, and passing task_evidence records use the host's native model boundary to judge meaning in the source language. pi-tasks prefers Pi classifier models, falls back to Pi's structured modelRegistry.streamSimple(), and uses Oh My Pi's runEphemeralTurn() when Pi model APIs are unavailable. It does not ship a provider SDK or call an external model endpoint directly.

The assessor handles English, Traditional and Simplified Chinese, Japanese, Korean, and mixed technical text under one language-neutral policy. It judges whether operations are independently executable or verifiable; a conjunction, filename, keyword, or text length is never sufficient by itself. Task and evidence fields are quoted as untrusted data, and typed model output is validated before persistence.

Successful results are stored in version 2 task events with their input hash, model provenance, prompt version, confidence, and decision. Replay, resume, branch navigation, rendering, and completion remain deterministic and never re-run inference. Existing version 1 sessions continue to replay as legacy history.

Semantic calls consume model tokens and can add latency. Pi classifier/chat calls send only the assessment payload. Oh My Pi ephemeral turns may include the current conversation snapshot according to the host's side-turn contract; use the same data-handling policy as the active OMP conversation. If all native boundaries are unavailable or return invalid output, the mutation fails closed with a retry instead of reverting to regex heuristics.

On session_start and session_tree, pi-tasks performs a static capability preflight. It inspects Pi classifier metadata and the presence of Pi chat or OMP ephemeral APIs without sending a model request. Healthy sessions stay silent. If no native assessor is available, a deduplicated warning and pi-tasks-semantic status direct the user to /tasks doctor before a protected mutation can fail.

/tasks doctor displays the three-strategy capability matrix without inference. /tasks doctor live is an explicit opt-in synthetic assessment that reports the actual strategy, provider, model, latency, and token usage when the host returns it. The probe does not read or mutate task state. Under Oh My Pi, the host may still include the current conversation snapshot under its side-turn contract.

Agent Tools

Recovery contracts

• Decomposition stops at depth 4. A still-non-atomic step then recommends an explicit task_update blocker so its remaining scope can be planned as a flat successor; pi-tasks never marks it done or creates the successor automatically.
• Evidence fields expose the same limits enforced by the reducer: summaries 500 characters, observed output 1,000, and each reference/source/command 300. Retry templates preserve valid values and replace invalid over-limit values with explicit placeholders.
• task_update.scope requires activity; scope_change and off_plan also require scope_reason. Missing fields return a targeted task_update recovery using the public snake_case parameter names.
• Empty or omitted criterionIds on new and decomposed steps auto-link the available task criteria; non-empty arrays must contain known generated IDs.
• Plan and decomposition quality is assessed from meaning in the source language through the native Pi/OMP model boundary. Caller-supplied granularityCheck fields are not accepted, and allowedActions is optional.
• Assessment failures are fail-closed and retryable. Rejected calls persist nothing, consume no task/evidence IDs, and never fall back to keyword regexes.

Completion Gates

task_complete rejects when:

• No evidence exists
• Any ordered plan step is still active or pending
• Required criteria are not satisfied
• A criterion is satisfied without evidence
• Unresolved blockers remain
• Unresolved scope drift warnings remain
• All evidence is only not_verified
• Linked failing step/criterion evidence remains unresolved by a later passing supersedes rerun

Forced completion requires force_with_reason and produces a low-confidence warning.

When a rerun passes after an honest failed gate, record the passing task_evidence with supersedes: ["<failed evidence id>"] and the same linked step_ids / criterion_ids; the failed evidence remains in lineage but no longer blocks completion.

Token Efficiency

Normal tool results return only the compact resume contract needed for the next action — not the full task state.

# Compact defaults during work:
task_next
task_resume
/tasks

# Detailed view only when debugging:
/tasks detail
task_list include_evidence=true

Custom task UI

pi-tasks publishes a versioned state snapshot after restoring its default widget and after every successful task mutation. Other Pi extensions can subscribe without importing or patching pi-tasks internals:

import type {
  ExtensionAPI,
  ExtensionContext,
} from "@earendil-works/pi-coding-agent";
import {
  TASK_STATE_EVENT,
  type TaskStateEvent,
} from "pi-tasks";

export default function customTaskUi(pi: ExtensionAPI) {
  let ctx: ExtensionContext | undefined;
  let latest: TaskStateEvent | undefined;

  const render = () => {
    if (!ctx || !latest) return;
    const active = latest.state.activeTaskId
      ? latest.state.tasks[latest.state.activeTaskId]
      : undefined;
    ctx.ui.setWidget(
      latest.widgetId,
      active ? [`Custom task: ${active.id} ${active.title}`] : undefined,
      { placement: "aboveEditor" },
    );
  };
  const attach = (nextCtx: ExtensionContext) => {
    ctx = nextCtx;
    render();
  };

  pi.on("session_start", (_event, nextCtx) => attach(nextCtx));
  pi.on("session_tree", (_event, nextCtx) => attach(nextCtx));
  pi.on("session_shutdown", () => {
    ctx = undefined;
    latest = undefined;
  });
  pi.events.on(TASK_STATE_EVENT, (value: unknown) => {
    if (
      !value ||
      typeof value !== "object" ||
      (value as { version?: unknown }).version !== 1
    ) return;
    latest = value as TaskStateEvent;
    render();
  });
}

Event contract:

• name: pi-tasks:state (TASK_STATE_EVENT);
• payload version: 1;
• reasons: session_start, session_tree, or task_mutation;
• widgetId: stable default widget key, currently pi-tasks;
• state: structured-cloned task snapshot with event history omitted.

The default widget is installed before publication, so a synchronous subscriber may replace it through the supported widget key. With no subscriber, existing pi-tasks UI behavior is unchanged. Consumer mutations affect only their cloned snapshot, never runtime task state. Payloads can include task text, decisions, blockers, and evidence references; custom UI extensions should keep them local.

Technical Details

Capabilities

• Typed task, acceptance criterion, evidence, decision, blocker, and event model
• Pure reducer with transition validation and evidence-before-completion enforcement
• Ordered plan steps; agents must complete or skip the current step before advancing
• Step-level contracts with expected output, linked criteria, required evidence, and optional allowed actions
• Native-model plan quality assessment distinguishes one semantic operation from independently executable or verifiable work across supported source languages
• Persisted version 2 semantic provenance keeps session replay deterministic and model-free while retaining version 1 history compatibility
• Recursive decomposition gate for model-assessed non-atomic steps, with explicit blocker recovery at depth 4
• Step-scoped evidence through task_evidence.step_ids
• Current-step evidence lock unless explicit override_reason is supplied
• Evidence quality gate: traceable, reproducible, with artifact references
• Evidence budget gate with schema-visible limits and bounded retry templates
• Tool rejections include structured recovery details and targeted correction before task_resume guidance
• task_next one-step weak-model contract with mode, current-step lock, recommended tool, blocked tools, minimum params
• Scope drift recording for scope_change and off_plan activity
• Derived progress from completed steps, satisfied criteria, and evidence
• Duplicate evidence detection
• Branch-aware persistence via Pi custom entries (pi-tasks:event)
• Session replay from ctx.sessionManager.getBranch() on session_start and session_tree
• Compaction snapshot hook via session_before_compact
• Compact status bar and above-editor widget
• Oh My Pi-compatible extension manifest, with critical entrypoint guidance preserved in descriptions for hosts that ignore custom promptSnippet/promptGuidelines fields
• Inference-free startup semantic capability preflight, deduplicated unavailable warning, and /tasks doctor diagnostics

Verification

Local verification suite:

• PI_SDK_ROOT=/path/to/@earendil-works/pi-coding-agent npm run release:check (typecheck + lint + unit/native tests + build + import smoke + pack + audit)
• Real Pi 1.4.0 and Oh My Pi 18.14.1 dogfood most recently passed on 2026-10-31.

Dogfood coverage includes: native Pi chat and OMP ephemeral semantic assessment, inference-free healthy startup, static and live /tasks doctor, English and Traditional Chinese task creation, task updates, same-session resume, Pi fork replay, /tasks, clean /quit, and installed-tarball smoke.

Documentation

• Product Plan — positioning, scope, research, and /goal boundary
• Implementation Specification — data contracts, reducer rules, tool contracts, TUI spec
• Dogfood Checklist — real Pi dogfood scenarios and status
• Weak-Model Prompts — English and Traditional Chinese validation prompts
• Release Process — gates required before publishing

License

MIT