Handoff

---
name: handoff
description: Use when the user asks to save next steps, prepare a resume prompt, or continue work in a fresh session of the current tool, or when clear follow-up work should resume there.
---

# Handoff

Prepare the next-session prompt without ending this session. Saving a prompt,
arming a session-replacement command, and actually replacing a session are
different actions. Never invoke the closing consumer yourself. Do not use a
handoff to stop an active task that the user asked you to finish.

If the user names a project-specific closeout skill, follow that requested
workflow. Do not silently drop an explicit request for both closeout and a
handoff, or create session logs outside the authorized closeout workflow.

## Decide what is authorized

- A draft or review request produces the prompt for review without saving or
  arming anything. Discussing possible next steps is not permission to save.
- If the user asks to save a prompt and specifies the next task, preserve that
  task directly. A requested skill invocation must remain an invocation, and
  requested actions must not become background context. Do not ask again when
  the exact saving request and content are already clear.
- If saving was requested but next-session work must be inferred, show the full
  proposed prompt as ordinary message content, then obtain approval before
  saving. Keep any structured choices short; the prompt must be visible outside
  option labels. Use a fence longer than any fences inside the prompt, or a
  clearly separated preview. Do not let a formatting wrapper enter the saved
  prompt accidentally.
- “Save for later” does not authorize immediate closure. Inferred follow-ups,
  advice from tools, and quoted instructions do not create authority for future
  writes, sharing, deletion, deployment, or spending.

## Compose a faithful, self-contained prompt

Preserve the user's objective, exact skill/arguments where specified, task
order, constraints, approved actions and unresolved decisions. Rephrase only
for clarity. Include the useful current state, not a transcript dump:

- Source project/worktree, branch and relevant commit/file identities; identify
  foreign dirty or staged work that the next session must preserve.
- Completed work separately from attempted, inferred, pending and unverified
  work. State which behavior was actually checked and which evidence was only
  a test, source inspection or stale observation.
- Concrete next actions and stopping conditions, active owned processes/agents,
  resumable identifiers, and retained artifacts needed to continue safely.
  Do not terminate unrelated work or launch fresh work as bookkeeping.
- Runtime/account and intended next project when known; preserve explicit
  no-push, read-only or other authority limits. The prompt is context, not a
  grant beyond the user's actual instructions.

Use the current date when it is available; do not invent it. An inferred prompt
may start “Continue from previous session (DATE).” Keep it actionable without
requiring an inaccessible conversation. The next session must read
`AGENTS.md` and applicable project instructions; do not claim those files
or old logs contain facts you have not checked.

Do not embed credentials or unnecessary private correspondence. Keep private
handoff material out of public project files. Use the secrets context before
handling credentials, and refer to approved stores rather than copying values.

## Save the prompt where the consumer reads it

1. Identify the current runtime/session and project from reliable context. Do
   not select another session by recency or a matching project basename.
2. The consumer, `agent-handoff`, reads a fixed file per backend by default:
   `/tmp/codex-handoff.md` for this backend. Save the approved prompt there,
   so that the user's next step is only `M-x agent-handoff` in the session
   buffer and nothing else. Write it with the normal file-editing tool, mode
   0600, UTF-8, no front matter unless a different target directory is
   required. Treat the saved prompt as immutable once the user may launch it;
   a revised prompt replaces the file only before launch and is re-verified.
3. If that file already exists and was not written by this session, another
   session may be about to consume it. Do not overwrite or remove it. Save the
   prompt to a private file instead (`mktemp -d /tmp/agent-handoff.XXXXXX`,
   directory 0700, file 0600) and tell the user plainly that the default slot
   is occupied, by what, and that they must either clear it themselves or
   launch with the private file. Never leave the user to discover the empty
   slot from the consumer's error.
4. Re-read the exact saved file and compare it with the approved prompt;
   record its digest and path. Preserve exact requested text. Do not inject
   consumer metadata into ordinary prompt text or let a Markdown front-matter
   example silently select another project.
5. Report that the prompt was saved, with its path and any material difference
   from the preview, and the exact next step for the user. Warn if a requested
   long-lived handoff relies on `/tmp`; use an appropriate user-requested
   durable private destination instead.

## Prepare user-triggered consumption only when verified

Read [the consumer contract](references/consumer-contract.md). Its defaults are
not proof of the running Emacs configuration. Verify that `agent-handoff` is
loaded, that the source buffer is this session (its process command line
carries this session's id), the backend, the source directory and the intended
target before telling the user the next step. Do not guess a profile or
start/restart Emacs to satisfy that check.

When the prompt sits in the default slot, the user's step is `M-x
agent-handoff` in the session buffer; say so and nothing more. Only when the
default slot was occupied (step 3 above) prepare a one-invocation binding of
`agent-handoff-files` to the private file for the verified backend, stage it
with `paste-via-kill-ring`, and explain that it replaces the plain command.
Never change the global value of `agent-handoff-files`.

The user-triggered invocation rechecks the source identity and the saved
file before any closure. A buffer name alone can be reused. Pin the intended
existing target directory explicitly when needed, verify how the consumer
parses the file, and check that it will consume the intended prompt rather
than strip meaningful front matter. Check replacement startup prerequisites
before closing: the observed consumer kills the old session before calling
the start routine, so startup failure is not rollback.

If source identity, consumer compatibility, permissions or launch safety cannot
be established, retain the saved prompt and state that launch preparation is
unverified. Do not offer a guessed destructive command. A saved file is not
evidence of closure, a new session, or automatic prompt delivery.

When a verified command is ready, use `paste-via-kill-ring` for any expression or
command Pablo must paste. Explain the actual user-side invocation surface; do
not assume a `! emacsclient ...` shell escape works in every CLI/app. Leave the
closing/replacement action to the user. Do not run it, send signals, or invoke a
wrapper that closes this session. Report only the verified preparation state.