handoff-cli 0.3.0__tar.gz → 0.3.4__tar.gz

handoff_cli-0.3.4/CLAUDE.md

@@ -0,0 +1,45 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What handoff is
+
+A CLI proxy that dispatches coding tasks to configurable AI backends — Claude (any Anthropic-compatible endpoint) and Codex (`codex exec`). Users invoke it as a Claude Code skill or Codex subagent, rarely typing `handoff` directly.
+
+## File map
+
+```
+cli/
+├── main.py                  # Entry point: parses argv[1], dispatches to cli/commands/<cmd>.py
+├── config.py                # Loads ~/.handoff/config.yaml (user config), deep-merges with backend_types.yaml (mechanism)
+├── backend.py               # Resolves backend config → CLI args + env vars for claude/codex subprocess
+├── core.py                  # SQLite state (~/.handoff/runs/handoff.db), run ID allocation, legacy migration
+├── stream.py                # execute_run(): spawn backend, parse JSONL stream, write .out.txt / .result.md
+├── tui.py                   # Textual TUI for `handoff list` (DataTable, detail view, auto-refresh)
+├── jsonl_parser.py          # Low-level JSONL line parser
+├── jsonl_viewer.py          # JSONL log viewer (used by TUI detail panel)
+├── backend_types.yaml       # Mechanism contract: how each backend TYPE is launched (command, PTY, flags). NOT user-overridable.
+├── user_config_template.yaml# Template for `handoff init` → ~/.handoff/config.yaml
+├── commands/
+│   ├── run.py               # `handoff run` — execute a prompt against a backend
+│   ├── new.py               # `handoff new` — pre-allocate run_id, print prompt file path
+│   ├── list.py              # `handoff list` / `handoff ls` — TUI or plain-text listing
+│   ├── resume.py            # `handoff resume` — reopen or continue a past conversation
+│   ├── tail.py              # `handoff tail` — live-tail a run's output stream
+│   ├── init.py              # `handoff init` — create config, symlink skill/agent files
+│   └── env.py               # `handoff env` — print config/data paths
+└── skills/
+    ├── handoff-ds/SKILL.md   # Claude Code skill → deepseek backend
+    ├── handoff-codex/SKILL.md# Claude Code skill → codex backend
+    ├── handoff-opus/SKILL.md # Claude Code skill → opus backend
+    └── handoff-ds.toml       # Codex subagent definition → deepseek backend
+```
+
+## How to release
+
+1. Bump `version` in `pyproject.toml`
+2. Commit: `git commit -m "release: vX.Y.Z"`
+3. Tag: `git tag vX.Y.Z`
+4. Push: `git push && git push --tags`
+
+Pushing a `v*` tag triggers `.github/workflows/publish.yml` → builds with `uv build`, publishes to PyPI, creates a GitHub Release.

{handoff_cli-0.3.0 → handoff_cli-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: handoff-cli
-Version: 0.3.0
+Version: 0.3.4
 Summary: Multi coding-agent task dispatcher — a CLI proxy for claude that sends coding tasks to configurable AI backends
 Requires-Python: >=3.9
 Requires-Dist: pyyaml<7,>=6

handoff_cli-0.3.4/README.md

@@ -0,0 +1,207 @@
+<div align="center">
+<img src="docs/assets/handoff-hero.jpg" width="100%" alt="hero">
+
+# With **Handoff**, your coding agents can finally work together.
+
+
+| coding agent | → Hand off to | Why |
+| :-- | :-- | :-- |
+| Claude Code / Codex | **DeepSeek** | Execution work is fast and cheap; save the expensive quota for decisions |
+| DeepSeek | **Codex / Opus** | Borrow a brain for hard problems, bring the answer back to your session |
+
+No tool-switching, no lost context.
+
+**English** · [简体中文](README.zh-CN.md)
+
+</div>
+
+## Why handoff
+
+If you use more than one coding agent, these will sound familiar:
+
+- 💸 **"Claude / Codex: the $20 plan never lasts. The $100 plan costs too much."**<br>
+  — Just say: *"Give this task to `/handoff-ds`."* DeepSeek does the work fast and cheap. Save your expensive quota for decisions.
+- 🤔 **"DeepSeek is stuck. I want a second opinion from Codex."**<br>
+  — Just say: *"Ask `/handoff-codex` what it thinks."* No new terminal. No re-explaining. The answer comes back to your current session.
+- 🔁 **"I want to continue that task from before."**<br>
+  — Just say: *"Resume that `/handoff-ds` session."* Everything is still there: the files it changed, the code it read, what it concluded.
+- 🔄 **"A new model means a new session. I have to explain everything again."**<br>
+  — Don't switch. Stay in your session. handoff passes the task over, then brings the result back.
+
+**Do the math:** for transactional work — writing code, running tests — DeepSeek V4 matches Sonnet-class models at a fraction of the price. What is really scarce, and worth a subscription, is the judgment of the one or two models at the very top (Opus / GPT-5.5).
+
+| Option | Relative cost for the same work |
+| --- | --- |
+| Claude Sonnet | 1× (baseline) |
+| DeepSeek official API | **1/3** |
+| [OpenCode Go](https://opencode.ai/go?ref=D5926WCTD8) (includes DeepSeek V4) | **1/18** |
+
+Let the top model talk to you, split the work, and review; hand all execution off — **a $20 subscription directing $5 of compute gets you ~$200 worth of work.** That's all there is to it: one sentence inside your agent session.
+
+## Quick start
+
+### 1. Install
+
+```bash
+uv tool install handoff-cli
+handoff init        # creates the config, links skill / agent files
+```
+
+Upgrade with `uv tool upgrade handoff-cli`.
+
+### 2. Set your token
+
+opus / codex reuse your local claude / codex logins — zero config. **Only DeepSeek needs a token.**
+
+For DeepSeek compute we recommend the [OpenCode Go plan](https://opencode.ai/go?ref=D5926WCTD8) (lowest cost, includes DeepSeek V4). Once you have a key, edit `~/.handoff/config.yaml` and change just the `ANTHROPIC_AUTH_TOKEN` line:
+
+```yaml
+# ~/.handoff/config.yaml — handoff init generates this for you
+backends:
+  deepseek:                          # ← first = default
+    type: claude
+    model: deepseek-v4-flash
+    pro_model: "deepseek-v4-pro[1m]"
+    env:
+      ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic
+      ANTHROPIC_AUTH_TOKEN: "sk-..."  # ← change this. Local proxy setup: https://github.com/iTzFaisal/oc-cc-proxy
+      ANTHROPIC_MODEL: "{model}"
+
+  opus:                              # local claude login — zero config
+    type: claude
+    ...
+  codex:                             # local codex login — zero config
+    type: codex
+    ...
+```
+
+### 3. Dispatch your first task
+
+Go back to Claude Code and say:
+
+> Make a plan, then hand it to `/handoff-ds`.
+
+The task runs in the background; your session is never blocked. When it finishes, the agent reads the result and reports back.
+
+### 4. Who you can hand work off to
+
+| What you say | From | Hands off to | Best for |
+| --- | --- | --- | --- |
+| `/handoff-ds` | Claude Code | DeepSeek V4 | Execution work: writing code, running tests, refactors, bulk edits |
+| `handoff-ds` (subagent) | Codex | DeepSeek V4 | Same as above — use this when you're inside Codex |
+| `/handoff-codex` | Claude Code | Codex (GPT-5.5) | Heavy reasoning, second opinions, hard bugs |
+| `/handoff-opus` | Claude Code | Claude Opus | Decisions that deserve the top model |
+
+> Codex has no slash commands, so that row is the subagent of the same name — say "have `handoff-ds` execute the task above."
+
+### 5. Watch progress / browse history
+
+Inside Claude Code, expand the background shell and the live progress is right there — it renders in the shell view and uses none of your main session's context. To browse history or follow a task on its own, use `handoff list` and `handoff tail` (see the FAQ below).
+
+## FAQ
+
+<details>
+<summary><b>How do I browse the task list or watch a task's progress?</b></summary>
+
+<br>
+
+Dispatching and resuming are the AI's job (`handoff run` / `handoff resume` under the hood). These two commands are for you — browse the list, watch the progress:
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+**`handoff list` / `handoff ls`** — interactive TUI over your full task history. See the full prompt, live status, and final result; press `G` on a row to reload that conversation and keep chatting.
+
+</td>
+<td width="50%" valign="top">
+
+**`handoff tail <run-id>`** — follow a task's output stream live, like looking over its shoulder.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+<!-- docs/assets/list-tui.jpg — ~480px wide — TUI list + detail view, highlight G/C shortcuts -->
+<img src="docs/assets/list-tui.jpg" width="100%" alt="handoff list interactive TUI">
+
+</td>
+<td valign="top">
+
+<!-- docs/assets/tail.jpg — ~480px wide — handoff tail live stream -->
+<img src="docs/assets/tail.jpg" width="100%" alt="handoff tail live follow">
+
+</td>
+</tr>
+</table>
+
+</details>
+
+<details>
+<summary><b>Can I dispatch several tasks at once?</b></summary>
+
+<br>
+
+Yes. Have your agent send off several tasks in one message. Each runs on its own and reports back on its own — they never get in each other's way.
+
+<!-- docs/assets/parallel.jpg — ~621px wide — 2–3 background tasks from one message, each with its own RESULT= path -->
+<img src="docs/assets/parallel.jpg" width="621" alt="Parallel dispatch">
+
+</details>
+
+<details>
+<summary><b>No uv / installing from source?</b></summary>
+
+<br>
+
+`pipx install handoff-cli` or `pip install handoff-cli` work just as well. From source:
+
+```bash
+git clone https://github.com/dazuiba/handoff && cd handoff
+uv tool install -e .
+handoff init
+```
+
+</details>
+
+<details>
+<summary><b>How do I add a custom backend / what goes in the env block?</b></summary>
+
+<br>
+
+Add one more entry under `backends` — any Anthropic-compatible endpoint works:
+
+```yaml
+backends:
+  kimi:
+    type: claude
+    model: kimi-k3
+    env:
+      ANTHROPIC_BASE_URL: https://api.moonshot.cn/anthropic
+      ANTHROPIC_AUTH_TOKEN: "${MOONSHOT_API_KEY}"
+      ANTHROPIC_MODEL: "{model}"
+```
+
+The env block is entirely yours — every key=value you set is exported before the CLI launches. `{model}` substitutes the resolved model name, `${ENV_VAR}` expands from your shell. Run `handoff env` to see where everything lives. Full details: **[configuration docs (Chinese) →](docs/configuration.zh-CN.md)**.
+
+</details>
+
+<details>
+<summary><b>How does it actually work?</b></summary>
+
+<br>
+
+1. Your agent hands the whole task to handoff, which runs it **in the background** — your session never blocks.
+2. handoff launches the matching CLI (`claude -p` / `codex exec`) in an isolated context and streams the full output to disk.
+3. The main session receives exactly one line: `RESULT=<path-to-result-file>`. Progress goes to the background shell view — **never** into your main context.
+4. On completion the agent gets notified, reads the result file, and reports back to you.
+5. The `RESULT=` path is also a stable handle for the conversation: every follow-up round resumes the same session.
+
+</details>
+
+**More docs**
+
+- **[CLI reference (Chinese) →](docs/cli-reference.zh-CN.md)** — full usage of `run` / `resume` / `list` / `tail` / `env` / `init`, run-id encoding, on-disk file layout.
+- **[Configuration (Chinese) →](docs/configuration.zh-CN.md)** — mechanism vs data layers, env block, `${ENV}` interpolation, include, custom backends.
+- **[Design notes (Chinese) →](docs/design.zh-CN.md)** — why Claude Code uses background shells while Codex uses a subagent; the RESULT= protocol.

handoff_cli-0.3.4/README.zh-CN.md

@@ -0,0 +1,209 @@
+<div align="center">
+<img src="docs/assets/handoff-hero.jpg" width="100%" alt="hero">
+
+# 有了 **Handoff**，你手里的几个 coding agent 终于可以互相协作了。
+
+
+
+
+| coding agent | → 派给 | 为什么 |
+| :-- | :-- | :-- |
+| Claude Code / Codex | **DeepSeek** | 执行性工作又快又便宜，旗舰额度留给决策 |
+| DeepSeek | **Codex / Opus** | 难题借个脑子，答案带回当前会话 |
+
+不用切来切去，也不丢上下文。
+
+[English](README.md) · **简体中文**
+
+</div>
+
+## 为什么需要 handoff
+
+如果你同时用着几家 coding agent，这些场景你一定眼熟：
+
+- 💸 **「Claude / Codex 订阅：$20 的量太少不经用，$100 的又太贵用不起」**<br>
+  — 只需一句：*「把这个任务交给 `/handoff-ds` 做」*。执行性工作 DeepSeek 干得又快又便宜，旗舰额度留给决策。
+- 🤔 **「DeepSeek 干活时卡住了，想听听 Codex 的意见」**<br>
+  — 只需一句：*「问问 `/handoff-codex` 的意见」*。不用开新终端、复述半天背景，答案带回当前会话。
+- 🔁 **「想接着上次派出去的活儿继续」**<br>
+  — 只需一句：*「接着刚才那个 `/handoff-ds` 的会话继续」*。之前改过的文件、读过的代码、得出的结论全都还在。
+- 🔄 **「想换个模型干活，就得重开会话、重述一遍背景」**<br>
+  — 不用换。你始终留在熟悉的会话里，handoff 在中间转交任务、拿回结果。
+
+**算笔账就明白了**：写代码、跑测试这类事务性工作，DeepSeek V4 不输 Sonnet 级模型，价格只有零头。真正稀缺、值得付订阅费的，是顶端那一两个模型（Opus / GPT-5.5）的判断力。
+
+| 方案 | 相对单价（干同样的活） |
+| --- | --- |
+| Claude Sonnet | 1×（基准） |
+| DeepSeek 官方 API | **1/3** |
+| [OpenCode Go](https://opencode.ai/go?ref=D5926WCTD8)（含 DeepSeek V4） | **1/18** |
+
+旗舰模型负责沟通、拆解、验收；执行全部 handoff 出去——**$20 的订阅指挥 $5 的算力，干出 ~$200 的活**。这就是 handoff 的全部用法：在你的 agent 会话里说一句话。
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+uv tool install handoff-cli
+handoff init        # 初始化配置，链接 skill / agent 文件
+```
+
+更新：`uv tool upgrade handoff-cli`。
+
+### 2. 配 token
+
+opus / codex 走你本机的 claude / codex 登录态，零配置；**只有 DeepSeek 需要填一个 token**。
+
+DeepSeek 算力推荐走 [OpenCode Go 套餐](https://opencode.ai/go?ref=D5926WCTD8)（单价最低，含 DeepSeek V4）。拿到 key 后，编辑 `~/.handoff/config.yaml`，只改 `ANTHROPIC_AUTH_TOKEN` 这一行：
+
+```yaml
+# ~/.handoff/config.yaml —— handoff init 帮你生成
+backends:
+  deepseek:                          # ← 第一个 = 默认
+    type: claude
+    model: deepseek-v4-flash
+    pro_model: "deepseek-v4-pro[1m]"
+    env:
+      ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic
+      ANTHROPIC_AUTH_TOKEN: "sk-..."  # ← 改这里。本地代理设置见 https://github.com/iTzFaisal/oc-cc-proxy
+      ANTHROPIC_MODEL: "{model}"
+
+  opus:                              # 本机 claude 登录态，零配置
+    type: claude
+    ...
+  codex:                             # 本机 codex 登录态，零配置
+    type: codex
+    ...
+```
+
+### 3. 派第一个活
+
+回到 Claude Code，对它说：
+
+> 制定计划，交给 `/handoff-ds` 执行。
+
+任务进入后台执行，不阻塞你的会话；完成后 agent 自动读取结果、向你汇报。
+
+### 4. 能派给谁
+
+| 你怎么说 | 从 | 派给 | 适合 |
+| --- | --- | --- | --- |
+| `/handoff-ds` | Claude Code | DeepSeek V4 | 写代码、跑测试、重构、批量修改等执行性工作 |
+| `handoff-ds`（subagent） | Codex | DeepSeek V4 | 同上——你人在 Codex 里时走这条 |
+| `/handoff-codex` | Claude Code | Codex (GPT-5.5) | 复杂推理、第二意见、疑难调试 |
+| `/handoff-opus` | Claude Code | Claude Opus | 需要顶级模型出马的关键决策 |
+
+> Codex 里没有 slash 命令，所以那行是同名 subagent：说「让 `handoff-ds` 执行上述任务」即可。
+
+### 5. 盯进度 / 看历史
+
+在 Claude Code 里展开那条后台 shell，实时进度流就在那里——走 shell view，不烧主会话上下文。想单独浏览历史、实时跟踪，用 `handoff list` 和 `handoff tail`（详见下方 FAQ）。
+
+## FAQ
+
+<details>
+<summary><b>怎么看任务列表、盯某条任务的进度？</b></summary>
+
+<br>
+
+派发和续接是 AI 的事（背后是 `handoff run` / `handoff resume`）；下面这两个命令给你——看列表、盯进度：
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+**`handoff list` / `handoff ls`** — 交互式 TUI，浏览全部历史任务。看 prompt 全文、实时状态、最终结果；选中按 `G` 直接把那次会话重新加载进来接着聊。
+
+</td>
+<td width="50%" valign="top">
+
+**`handoff tail <run-id>`** — 实时跟踪某条任务的输出流，相当于盯着它干活。
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+<!-- docs/assets/list-tui.jpg — 建议 ~480 宽 — TUI 列表 + 详情视图，圈出 G/C 快捷键 -->
+<img src="docs/assets/list-tui.jpg" width="100%" alt="handoff list 交互式 TUI">
+
+</td>
+<td valign="top">
+
+<!-- docs/assets/tail.jpg — 建议 ~480 宽 — handoff tail 实时输出流 -->
+<img src="docs/assets/tail.jpg" width="100%" alt="handoff tail 实时跟踪">
+
+</td>
+</tr>
+</table>
+
+</details>
+
+<details>
+<summary><b>能同时派发多个任务吗？</b></summary>
+
+<br>
+
+可以。在同一条消息里让 agent 派出多个任务，各自独立执行、独立完成通知，互不干扰。
+
+<!-- docs/assets/parallel.jpg — 建议 621 宽 — 同一条消息派发 2~3 个后台任务，各自拿到不同 RESULT= 路径 -->
+<img src="docs/assets/parallel.jpg" width="621" alt="并行派发多任务">
+
+</details>
+
+<details>
+<summary><b>没有 uv / 想从源码装？</b></summary>
+
+<br>
+
+`pipx install handoff-cli` 或 `pip install handoff-cli` 同样可用。源码安装：
+
+```bash
+git clone https://github.com/dazuiba/handoff && cd handoff
+uv tool install -e .
+handoff init
+```
+
+</details>
+
+<details>
+<summary><b>怎么加一个自定义后端 / env 块怎么写？</b></summary>
+
+<br>
+
+`backends` 下再加一项即可，任何 Anthropic 兼容端点都行：
+
+```yaml
+backends:
+  kimi:
+    type: claude
+    model: kimi-k3
+    env:
+      ANTHROPIC_BASE_URL: https://api.moonshot.cn/anthropic
+      ANTHROPIC_AUTH_TOKEN: "${MOONSHOT_API_KEY}"
+      ANTHROPIC_MODEL: "{model}"
+```
+
+env 块完全由你定义——你设的每个 key=value 都会在拉起 CLI 前导出为环境变量。`{model}` 替换为解析出的模型名，`${ENV_VAR}` 从当前 shell 展开。运行 `handoff env` 看各路径在哪。完整细节见 **[配置文档 →](docs/configuration.zh-CN.md)**。
+
+</details>
+
+<details>
+<summary><b>它到底是怎么工作的？</b></summary>
+
+<br>
+
+1. 你的 agent 把任务整包交给 handoff，**后台执行**，会话不阻塞。
+2. handoff 在独立上下文里拉起对应的 CLI（`claude -p` / `codex exec`），完整输出流式落盘。
+3. 主会话只拿到一行 `RESULT=<结果文件路径>`；执行进度打在后台 shell view，**不进**主会话上下文。
+4. 完成后 agent 收到通知，读取结果文件，向你汇报。
+5. `RESULT=` 路径同时是这个会话的稳定句柄——之后每轮续接都指向同一个会话。
+
+</details>
+
+**更多文档**
+
+- **[命令参考 →](docs/cli-reference.zh-CN.md)** — `run` / `resume` / `list` / `tail` / `env` / `init` 全部用法，run id 编码与落盘文件布局。
+- **[配置文档 →](docs/configuration.zh-CN.md)** — 机制与数据两层、env 块、`${ENV}` 插值、include、自定义后端。
+- **[设计说明 →](docs/design.zh-CN.md)** — 为什么 Claude Code 用后台 shell、Codex 用 subagent；RESULT= 协议细节。

handoff_cli-0.3.4/cli/__init__.py

@@ -0,0 +1,8 @@
+"""handoff CLI package."""
+
+try:
+    from importlib.metadata import version as _ver
+
+    __version__ = _ver("handoff-cli")
+except Exception:
+    __version__ = "0.0.0"

{handoff_cli-0.3.0 → handoff_cli-0.3.4}/cli/backend.py

@@ -28,6 +28,7 @@ Placeholder substitution:
 from __future__ import annotations
 
 import os
+import shlex
 import sys
 from typing import Optional
 
@@ -80,6 +81,26 @@ _CLAUDE_HERMETIC_VARS = (
 )
 
 
+def resolved_backend_env(backend: dict, model: str, pro_model: str = "") -> tuple[list[str], dict[str, str]]:
+    """Return env vars cleared and set for this backend after placeholder expansion."""
+    ctx = _base_ctx(backend, model=model, pro_model=pro_model)
+    unset_keys = list(_CLAUDE_HERMETIC_VARS) if backend_type(backend) == "claude" else []
+
+    resolved_env: dict[str, str] = {}
+    env_map = backend.get("env", {})
+    for key, val in env_map.items():
+        resolved = _resolve_env_val(val, ctx)
+        if resolved == "":
+            continue
+        resolved_env[key] = str(resolved)
+
+    if backend_type(backend) == "claude" and "CLAUDE_CONFIG_DIR" not in resolved_env:
+        config_dir = os.environ.get("CLAUDE_CONFIG_DIR") or os.path.expanduser("~/.claude")
+        resolved_env["CLAUDE_CONFIG_DIR"] = config_dir
+
+    return unset_keys, resolved_env
+
+
 def set_backend_env(backend: dict, model: str, pro_model: str = ""):
     """Set environment variables for the backend CLI.
 
@@ -88,26 +109,22 @@ def set_backend_env(backend: dict, model: str, pro_model: str = ""):
     known ANTHROPIC_*/model vars are cleared first, so only the backend's own
     env block takes effect.
     """
-    ctx = _base_ctx(backend, model=model, pro_model=pro_model)
+    unset_keys, resolved_env = resolved_backend_env(backend, model, pro_model)
 
-    if backend_type(backend) == "claude":
-        for key in _CLAUDE_HERMETIC_VARS:
-            os.environ.pop(key, None)
+    for key in unset_keys:
+        os.environ.pop(key, None)
+
+    for key, value in resolved_env.items():
+        os.environ[key] = value
 
-    env_map = backend.get("env", {})
-    for key, val in env_map.items():
-        resolved = _resolve_env_val(val, ctx)
-        # an empty value (e.g. a model-less legacy backend resolving
-        # ANTHROPIC_MODEL="{model}") must not be exported — an empty env var
-        # breaks the CLI where an unset one would not
-        if resolved == "":
-            continue
-        os.environ[key] = resolved
 
-    # claude needs a config dir; codex backends have no ANTHROPIC_*/CLAUDE_* env
-    if backend_type(backend) == "claude":
-        if not os.environ.get("CLAUDE_CONFIG_DIR"):
-            os.environ["CLAUDE_CONFIG_DIR"] = os.path.expanduser("~/.claude")
+def format_shell_command(cwd: str, cmd: list[str], unset_keys: list[str], set_env: dict[str, str]) -> str:
+    """Render a shell command that reproduces the backend invocation."""
+    parts = [f"cd {shlex.quote(cwd)}", "&&", "env"]
+    parts.extend(f"-u {shlex.quote(key)}" for key in unset_keys)
+    parts.extend(f"{key}={shlex.quote(value)}" for key, value in set_env.items())
+    parts.extend(shlex.quote(arg) for arg in cmd)
+    return " ".join(parts)
 
 
 def build_args(