---
name: plungeai-missions
description: "Run bounded autonomous PlungeAI agent missions (type: harness) — a goal, a tool fence, an iteration cap, and self-checked success criteria, via plungeai_run_mission or a harness workflow task. Use when the steps to reach a goal are not known in advance, when you need one open-ended researcher/verifier/analyst loop instead of a guessed chain of small tasks, or when the user asks for a bounded agent run. For a fixed pipeline of known steps use `plungeai-workflows`; for cron-scheduled missions use `plungeai-scheduling`; for a list-to-completion campaign ledger use `plungeai-campaigns`."
---

# PlungeAI Missions — bounded autonomous agent runs

A mission gives one agent a `goal`, a standing purpose, a fenced tool set, an
iteration cap, and success criteria it self-checks before finishing — then runs a
real ReAct loop (think → tool call → result → …) against it, hard-stopped at every
bound. Reach for a mission when the steps to reach the goal are NOT known in
advance; use a plain workflow (`plungeai-workflows`) when they are.

## Prerequisites

- A self-service `ozk_` API key from **Dashboard → One API → Keys**
  (https://dashboard.plungeai.com), or an MCP client already connected to
  `https://mcp.plungeai.com/v1`.
- Confirm identity first: `plungeai_whoami`.

## Discovery first

Never guess a skill, expert, persona, plugin, or MCP server id — a wrong id
degrades to a silent warning, not a hard failure. Look ids up live:
`plungeai_list_agents {kind: "skills"|"experts"|"personas"|"connectors", search:
"<topic>"}` (REST: `GET /v1/discovery/search?kind=…&q=…`).

## Running a mission — the two doors

**Quick, from an agent context** — `plungeai_run_mission` accepts a fixed subset of
the mission contract:

```
plungeai_run_mission {goal, mission?, allowed_tools?, max_iterations? (≤50),
                      success_criteria?, persona?, skills?, mode?: "sync"|"async"}
```

```json
{"user_request": "research the EU AI Act's impact on medical devices",
 "goal": "Produce a sourced brief on how the EU AI Act affects medical-device software vendors",
 "max_iterations": 12,
 "success_criteria": ["cites primary sources", "covers timelines and penalties"]}
```

Defaults to async: poll `plungeai_get_workflow_status`, fetch with
`plungeai_get_result`. A paused run (`⏸ AWAITING USER APPROVAL` / `AWAITING USER`)
is relayed to the user and resumed with `plungeai_continue`.

**Full control, as a workflow task** — anything beyond that subset (`experts`,
`backgrounds`, `plugins`, `mcp`, `model`/`provider`, `effort`, `max_parallel`,
`permissions`, `memory_owner`, `local`) requires a one-task `type: harness`
workflow, run with `plungeai_execute_workflow`:

```yaml
name: Claim verification
tasks:
  - type: harness
    goal: "Verify the claims in {input} and produce a sourced verdict"
    mission: |
      You are a careful researcher. Verify claims against primary sources.
      Refuse to conclude beyond the evidence.
    skills: [research]
    effort: standard
    allowed_tools: [web_search, web_fetch, task_complete]
    success_criteria:
      - Every verdict cites at least one primary source
```

Or reuse a pre-built agent card: `mission_ref: research-analyst` (equivalent
shorthand: a single-token `mission: research-analyst`). Cards are also directly
schedulable — see `plungeai-scheduling`.

## The tool fence — the core safety mechanism

`allowed_tools` is a hard whitelist: an out-of-fence tool call is refused by the
runtime, never just discouraged. Always include `task_complete`. Give the smallest
set that can achieve the goal — a verification mission needs `web_search,
web_fetch, task_complete`, not the file tools. Two loop runtimes exist (the
full-surface default, and the thin `universal-agent` registry-first fence,
selected with `agent:`); an explicit `allowed_tools` always wins over either
default. Full catalog and the agent fence / money-class protection:
`references/missions.md`.

## Gotchas

- No per-task `retry` on harness — mission runs are not idempotent; check
  `plungeai_executions` before re-firing anything with side effects.
- `success_criteria` are self-checked by the agent — treat them as guidance-grade,
  not proof.
- Merge order for cards is last-wins per key (card → workflow root → task), and
  **arrays REPLACE, never union** — a task-level `skills: [x]` replaces the whole
  card list.
- A run pauses (never dies) on `ask_user` questions or `permissions: ask` gates;
  resume with `plungeai_continue`, never retry around a pause.
- Memory: the platform recalls the owner's long-term memory as a frozen snapshot at
  run start and writes back durably mid-run — see `plungeai-memory`.

## Related skills

- `plungeai-workflows` — plain multi-step CNL pipelines; embed a mission as one task.
- `plungeai-scheduling` — cron a mission (or a `mission_ref` card) to run on its own.
- `plungeai-memory` — the recall/write lifecycle a mission runs against.
- `plungeai-skills-plugins` — the `skills`/`experts`/`persona`/`backgrounds`/`plugins`/`mcp` capability fields.
- `plungeai-results-traces` — read a mission run's status, output, and trace.
- `plungeai-campaigns` — running a list to completion instead of one bounded goal.

## Reference

- `references/missions.md` — full field reference, tool/agent fences, recursion
  guards, pre-built cards, and the `plungeai_run_mission` MCP tool contract.