agentctl-setup 是 sd0x-dev-flow 项目（sd0xdev/sd0x-harness 仓库）下的一项设置技能，用于引导用户选择性安装并配置 agentctl 扩展。agentctl 本身是随仓库提供、位于 mods/agentctl/ 的可选组件，安装 sd0x-dev-flow 并不会自动安装它，需通过本技能显式启用。
用途 agentctl 面向把任务交给 Claude 后离开、回来需要快速确认情况的使用场景，主要回答三个问题：任务是否仍在范围内、Claude 是否索取了超出需要的权限、测试通过是否仍然成立。此外它提供一行状态提示和无需模型调用的交接记录。
主要能力
- 范围约束：用户声明一次任务范围（允许编辑的目录、允许运行的测试命令等），范围之外的调用（如 git push、kubectl rollout、编辑允许目录之外的文件）会在执行前被拒绝并指明规则；只有用户亲自输入的一行指令才能变更范围。
- 提案与确认：Claude 可根据工单起草范围，扩展先预览，用户输入 /agentctl accept 后才绑定。即使没有任务，已识别的直接 git push、gh pr merge 和生产写入也会被拒绝；无法分类的操作交给 Claude Code 自身的权限提示或自动模式。
- 测试证据时效：测试运行会记录由 Git 派生的目录树指纹，之后被跟踪或未跟踪文件发生变化，结果会在 30 秒内被标记为过期，而非显示为“通过”；被忽略的文件、子模块内容和运行环境不在覆盖范围内。
- 状态与交接：提示符上方显示一行状态带，/agentctl 查看详情，/agentctl handoff 依据记录生成交接，不调用模型。
使用方式 技能支持四种调用形式：/agentctl-setup 按顺序执行第 1 至 5 步；--task 只生成范围提案后停止；--status 只输出 doctor 检查报告；--uninstall 只执行卸载。每种子命令输出一个 JSON 文档，需读取其中的 ok、problems、errors 字段判断结果。 默认流程依次为：以简表说明扩展用途并询问是否安装；运行 doctor 检查 Claude Code 版本、安装状态及问题；经用户批准后执行 claude plugin install agentctl@sd0xdev-marketplace（失败时提供 claude --plugin-dir 的会话内替代方案）；通过提问收集任务目标、可编辑目录、可运行检查命令和额外禁止项，将答案写入临时文件后由 task-line 生成任务行，并要求用户自行发送该行，不接受 Claude 代为发送；最后可选写入原生 permissions.deny 规则作为第二层防护。 --task 模式下按参考文档生成提案文件并验证，用户输入 /agentctl accept <摘要前 8 位> 或 /agentctl discard。卸载使用 claude plugin uninstall，扩展自身数据保留在 ~/.claude/plugins/store/agentctl_*.json，草拟提案保留在 ~/.claude/agentctl/proposals/，此前写入的拒绝规则仍留在设置文件中。
适用场景 适合希望为 Claude Code 增加任务范围约束、越权操作提前拒绝、测试结果时效提示和记录型交接的用户，也适合需要按项目或个人维度补充原生权限拒绝规则的配置场景。
限制 agentctl 不是安全边界、不是门禁、也不是审批机制，生产环境仍依赖凭证保护。它仅在运行时生效。该技能不用于审查或门禁变更（应使用 /codex-review-fast、/precommit），也不负责安装 sd0x-dev-flow 自身的规则、钩子或脚本（应使用 /install-rules、/install-hooks、/install-scripts）。自由文本答案不得放在命令行上，需经临时文件传入。安装、卸载和写入设置均须对应步骤的用户批准。