# manage_recall — Manual

## What it does
Controls scheduled recalls for the current session. Actions: cancel, skip, list.

## Parameters
- `action` (string, required) — `cancel`, `skip`, or `list`
- `session_id` (string, optional) — target session; defaults to current session

## Actions

### `cancel`
Removes the pending recall for the current session. Returns success only if a pending recall actually existed.

Use when:
- The user no longer needs the scheduled callback.
- You want to replace an existing recall with a new one (cancel old, then schedule new).
- The external condition the recall was waiting for has already resolved.

### `skip`
Advances a **recurring** recall by one interval. The next trigger time moves forward by `interval_seconds`.

Use when:
- The current scheduled check is unnecessary (e.g., user already confirmed the build passed).
- You want to pause the cycle for one beat without fully cancelling it.

Returns failure if there is no recurring recall pending.

### `list`
Shows all recalls for the target session (current session by default). Admins can list any session.

Output format:
```
Recalls for session <id>:

- [PENDING] once — trigger 2026-05-20T14:00:00+00:00
    comment: Check build status
    context: Read /tmp/build.log and report to user...
```

## Popular scenarios

### Cancel before rescheduling
User asks to change a 30-minute reminder to 1 hour. You must **cancel** the old one first, then schedule the new one — because only one pending recall per session is allowed.

### Skip a recurring check
A recurring recall checks `/var/log/myapp/errors.log` every 15 minutes. The user just told you they fixed the issue. Call `skip` to defer the next check by one interval. If the issue stays fixed, the user can ask you to cancel it entirely.

### List to verify state
Before telling the user "you have no pending recalls", call `list` to be sure. Before scheduling a new recall, call `list` to check if one already exists.

## Rules
1. Always check `list` before scheduling if you are unsure whether a recall already exists.
2. `cancel` + `schedule_recall` is the standard pattern for updating a timer.
3. `skip` only works on recurring recalls. For one-time recalls, use `cancel` if you want to abort.