Workspace Handoff

DotCraft workspaces are designed to cooperate with other coding agents. The .craft/ directory keeps the project rules, memory, session history, trace metadata, and tool evidence close to the repository, so you can hand off useful context without asking another agent to guess from chat fragments.

This page is for integrators and contributors who move a DotCraft thread into another coding agent. It covers finding the right thread, exporting it as a Markdown handoff, and what that export contains.

There are two collaboration modes:

Mode	Use when	Interface
Live client	The other tool can integrate with DotCraft directly	AppServer, ACP, SDKs, Desktop
Handoff document	The other coding agent only accepts files or prompt context	dotcraft context Markdown export

This page focuses on the handoff document flow. For live clients, see Unified Session Core and AppServer Mode.

What to share

A good external-agent handoff usually includes:

• The repository or the exact files the external agent may inspect.
• A dotcraft context export Markdown file for the relevant thread.
• The concrete task you want the external agent to do next.
• Any privacy constraints, such as whether tool outputs or memory history may be included.

Do not share provider credentials, global ~/.craft/config.json, or raw state databases unless you explicitly trust the receiver and need forensic debugging. A Markdown export is easier to limit and review than raw state, but it is not automatically safe to share. Minimize it with --tool-results and --history, then inspect it manually.

Find the right thread

When you know only a symptom, error, tool name, model id, or partial user request, search the workspace first:

dotcraft context search --query "provider timeout gpt-5.3" --workspace "D:\path\to\project" --limit 5

Search reads the workspace state DB first, including thread metadata, trace session bindings, trace session counters, and trace events. It then adds short rollout snippets for candidates. Results include an export command when the matching thread has a rollout file.

Search does not index internal exact-model-history or compaction-checkpoint payloads. Treat its snippets as discovery aids, then export the selected thread for the replayed conversation.

Use --json when another script or tool should consume the result:

dotcraft context search --query "thread_20260601" --workspace "D:\path\to\project" --json

Export a handoff

Once you have a thread id:

dotcraft context export --thread thread_20260601_ab12cd --workspace "D:\path\to\project" --output handoff.md

By default the export uses:

Option	Default	Why
--profile	handoff	Keeps the document shaped for another coding agent
--tool-results	summary	Preserves evidence without dumping full command or API output
--history	tail	Includes recent memory history without dragging in every old event

For a stricter handoff:

dotcraft context export --thread thread_20260601_ab12cd --tool-results none --history tail --output handoff.md

For the most detailed transcript:

dotcraft context export --thread thread_20260601_ab12cd --profile transcript --tool-results full --history full --output transcript.md

If --output is omitted, Markdown is written to stdout.

NOTE

--tool-results full removes only the exporter's preview-length cap for tool-result content already present in the session record. It does not retrieve original artifacts that were spilled to .craft/tool-results/, so the export may still contain only the recorded preview or reference.

What the export contains

The Markdown export includes:

• Export metadata: workspace, .craft path, rollout path, profile, and privacy modes.
• Thread metadata: status, timestamps, origin channel, display name, and turn count.
• Workspace memory: MEMORY.md, plus HISTORY.md according to the selected history mode.
• Continuity events: rollback and compaction records that affect context continuity.
• Current model-visible context: reconstructed from the latest usable compaction checkpoint plus surviving tail turns.
• Conversation: surviving turns replayed from canonical rollout JSONL.

The exporter redacts recognized sensitive keys in tool arguments and results, plus a limited set of sensitive text patterns. It does not scan every field as a secret: conversation messages, workspace memory, error text, and other free-form content may appear unchanged. Review every export before sharing it.

Reasoning content, free-form thread metadata, and internal provider or session payloads are omitted. Tool calls are kept, while tool and command results follow --tool-results. RequestUserInput answer bodies are always omitted, including from full exports; question text and correlation IDs remain.

Rollback and compaction

DotCraft does not treat rollout JSONL as a naive append-only transcript during export. It replays the canonical events:

• thread_rolled_back removes the rolled-back tail turns from the exported conversation and adds a continuity note.
• context_compacted records are listed as continuity events.
• The latest decodable compaction checkpoint whose covered turn still survives rollback is used for the "Current Model-Visible Context" section.
• If a checkpoint is corrupt or no longer applies, the exporter falls back to surviving rollout turns and prints a warning.

This matters because another coding agent needs the context that DotCraft would actually continue from, not stale turns that were already rolled back.

Handoff checklist

Before sending context to another coding agent:

1. Run dotcraft context search if the exact thread id is uncertain.
2. Export with --tool-results summary unless full outputs are needed.
3. Open the Markdown briefly and check for sensitive output.
4. Mention continuity warnings, especially rollback or ignored compaction checkpoints.
5. Tell the external agent what to do next and which files it may modify.

Related docs

• Project Workspace
• Unified Session Core
• Session persistence
• Observability
• AppServer Mode