# Background Tasks

Delegate work that takes >30 seconds. The task agent runs autonomously in a
separate CLI session while you keep chatting with the user.

## When to use

- Research, browsing, comparisons (flights, hotels, products, etc.)
- File creation, documents, code generation
- Any multi-step work that would block the conversation
- Parallel independent sub-tasks

## When NOT to use

- Quick questions answerable in seconds
- Trivial one-line operations

## Creating a task

```bash
python3 tools/task_tools/create_task.py --name "Flugsuche Paris" "Suche verfügbare Flüge nach Paris für 2 Personen im Juni. Vergleiche Preise und Airlines."
```

Options:
- `--name NAME` — human-readable task name (recommended)
- `--provider PROV` — override provider (claude, codex, gemini)
- `--model MODEL` — override model (opus, sonnet, flash, etc.)
- `--thinking LEVEL` — codex reasoning effort (low, medium, high)

**Important**: Include ALL context in the prompt. The task agent does NOT see
the conversation — give it everything it needs.

## Listing tasks

```bash
python3 tools/task_tools/list_tasks.py
```

## Cancelling a task

```bash
python3 tools/task_tools/cancel_task.py TASK_ID
```

## Resuming a completed task

Resume continues the task's CLI session — the agent keeps its full context
from the previous run. Use this instead of creating a new task when you want
to build on existing work.

```bash
python3 tools/task_tools/resume_task.py TASK_ID "jetzt nur 2-Wochen-Reisen suchen"
```

Runs on the **original provider/model**, regardless of current chat provider.

**When to resume vs. create new:**
- **Resume**: Refine results, follow-up questions, adjusted parameters,
  deliver additional info after an ask_parent question
- **New task**: Completely different work, unrelated to any previous task

### Resume examples

1. Task searched Python best practices → user wants more on testing
   → `resume_task.py TASK_ID "Jetzt speziell Testing best practices vertiefen"`

2. Task asked "Für wann?" via ask_parent → user says "Juni"
   → `resume_task.py TASK_ID "Reisezeitraum: Juni 2026, ab Frankfurt FRA"`

3. Task found flight options → user wants cheaper alternatives
   → `resume_task.py TASK_ID "Günstigere Alternativen suchen, Budget max 300€"`

## Inside a task (for task agents only)

When running as a background task agent, you can ask the parent agent:

```bash
python3 tools/task_tools/ask_parent.py "your question"
```

This forwards your question and returns immediately. The parent agent
will resume your task with the answer. After calling this, finish your
current work and update TASKMEMORY.md — you will be resumed.
