这个项目通过 Codex SessionStart Hook，为长任务追加一段精简的压缩连续性规则。它只解决一件事：上下文压缩后，Agent 仍然知道当前有效目标、已经探索或完成了什么、还有什么没做、下一步做什么，以及为什么现在还不能结束。
默认模型范围：
| 模型 | 压缩连续性 |
|---|---|
gpt-5.6-sol |
是 |
gpt-5.6-terra |
是 |
gpt-5.6-luna |
否 |
gpt-5.5 |
否 |
| 其他模型 | 否 |
这套方案不替换 Codex 官方模型、root、child-agent、工具、multi-agent mode 或 compact prompt，也不修改静态模型目录。自定义子 Agent 编排已经全部移除，子 Agent 行为完全交给 Codex 官方机制。
Important
Hook 能在本机执行命令。安装后请在 Codex 中打开 /hooks，核对命令和文件路径后亲自信任。不要使用 --dangerously-bypass-hook-trust 代替正常审查。
仓库地址：
https://github.com/hututuo/codex-long-task-continuity
可以把下面这段话直接交给 Agent：
请安装这个仓库提供的 Codex Long-Task Continuity Hook。先完整读取 README.md，确认真实 CODEX_HOME 和现有 hooks.json；克隆后先运行测试，再执行 install.py install。保留所有无关 Hook 和配置，安装前创建备份，不要覆盖 config.toml 或模型目录。升级时删除本项目旧的 subagent-orchestration.md，但保留 Codex 官方多 Agent 提示和功能。最后运行严格验证，并用新的 Sol、Terra 会话做正向检查，用 Luna、GPT-5.5 做负向检查。保留回滚路径，不要强制结束承载当前任务的 Codex 进程。
| 长任务问题 | 处理方式 |
|---|---|
| 大量读取后压缩，接手阶段不知道之前看过什么 | 保存已经探索、完成或修改的状态、关键证据和继续所需的准确位置 |
| 结论还没形成，压缩后只能重新探索 | 保存仍待确认的发现及其不确定性、工作停止点、缺口和下一方向 |
| 摘要写了待办，接手 Agent 却直接 Final | Completion gate 明确记录最终交付前必须完成或验证的事项 |
| 后来的用户要求已经覆盖旧要求，模型却反复纠结旧话题 | 只保留仍会影响下一步的可执行含义；已覆盖、完成或解决的内容视为 resolved/superseded 并从活跃状态中省略 |
| 摘要过长，重要的未完成项反而不醒目 | 只保留 Active objective、Established state、Continuation state 和 Completion gate 四类状态 |
安装器会在用户级 hooks.json 中结构化合并一个 Hook：
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|compact",
"hooks": [
{
"type": "command",
"command": "<python> <CODEX_HOME>/hooks/codex-long-task-continuity.py",
"statusMessage": "Loading Codex long-task continuity rules"
}
]
}
]
}
}运行顺序：
- 新任务触发
SessionStart source=startup。 - Hook 仅在活动模型是 Sol 或 Terra、来源是
startup或compact时输出压缩连续性规则。 - Codex 把 stdout 作为额外 developer context 加入任务。
- 第一次压缩时，官方 compact prompt 与这段补充规则共同生效。
- 压缩结束后，
SessionStart source=compact会在继续采样前再次注入这段规则，供后续任务和下一次压缩使用。
compact Hook 不是 compact prompt，也不会替换官方摘要格式。它只补充官方 prompt 没有明确表达的 active/resolved 状态、精确续作位置和完成门槛。
默认 CODEX_HOME 取环境变量 $CODEX_HOME；未设置时使用 ~/.codex。
| 目标路径 | 用途 |
|---|---|
$CODEX_HOME/hooks.json |
保留已有内容，只合并一个 SessionStart matcher group |
$CODEX_HOME/hooks/codex-long-task-continuity.py |
模型和事件范围过滤、提示词输出 |
$CODEX_HOME/prompt-overlays/compaction-continuity.md |
压缩后的可续作状态和 Completion gate |
$CODEX_HOME/backups/codex-long-task-continuity-* |
安装、升级或卸载前的精确备份和 manifest |
升级时，安装器会检查现有本项目 Hook 是否确实引用旧文件。只有确认属于本项目旧安装时，才会备份并删除：
$CODEX_HOME/prompt-overlays/subagent-orchestration.md
如果只是存在同名文件，但现有 Hook 没有引用它，安装器会保留文件并在验证时警告，避免误删用户自己的内容。
安装器不会修改：
$CODEX_HOME/config.tomlmodel_catalog_json指向的模型目录- Codex 官方 base instructions
- 官方 root、child-agent、tool 或 multi-agent mode 提示词
- 与本项目无关的其他 Hook
要求 Python 3.9 或更高版本，只使用 Python 标准库。
git clone https://github.com/hututuo/codex-long-task-continuity.git
cd codex-long-task-continuity
python3 -m unittest discover -s tests -v
python3 install.py install非默认 Codex Home：
python3 install.py --codex-home /absolute/path/to/codex-home install安装器会：
- 在任何写入前创建备份和 SHA-256 manifest；
- 保留无关 Hook；
- 原子写入活动文件；
- 幂等升级，不重复添加 Hook；
- 确认旧 Hook 所有权后，备份并移除旧的自定义子 Agent overlay；
- 拒绝无效 JSON、符号链接目标、非普通文件和越界恢复路径。
安装后：
- 在 Codex 输入
/hooks。 - 检查命令指向
$CODEX_HOME/hooks/codex-long-task-continuity.py。 - 信任 Hook。
- 运行：
python3 install.py verify --strict-legacy预期：
Verification passed: Sol/Terra receive the compaction prompt; Luna/GPT-5.5 receive no prompt.
验证会检查：
- 仓库源文件与安装文件逐字一致；
hooks.json中恰好有一个本项目 Hook；- matcher 是
startup|compact； - Sol、Terra 在
startup和compact各输出一次## Compaction continuity； - 输出中没有
## Sub-agent use； - Luna、GPT-5.5 和
resume不输出自定义内容； - 旧
subagent-orchestration.md已删除； - 是否仍存在旧版完整 root 覆盖或模型目录压缩段。
静态验证不能代替 Hook 信任，也不能证明真实模型调用已收到 developer context。最终验收应新建 Sol、Terra 任务检查正向注入，再用 Luna 和 GPT-5.5 检查没有自定义注入。
英文提示词 是安装时的唯一权威来源。它只保留四类状态：
Active objective：最新有效目标、交付物、范围、仍生效的约束和决定。Established state：已经探索、完成或修改的内容，关键证据，已确认和仍待确认的发现，以及续作所需的准确位置。Continuation state：工作停在哪里，准确的 pending / in-progress 计划和 TODO，还缺什么、哪些工作未验证，以及下一项具体行动。Completion gate：最终回复前仍必须完成或验证什么；只要存在必做项，任务就保持进行中或受阻。
压缩时保留早期内容的可执行含义，而不是保留已经回应过的对话包装。后续要求覆盖先前要求；已经完成、取消或解决的一次性担忧视为 resolved / superseded，并从活跃续作状态中省略。失败或排除路径只有在能够防止重复劳动或解释下一方向时才保留。
Codex 官方 compact prompt 仍是四项通用 checkpoint：当前进度和决定、重要上下文与约束、剩余工作、继续所需的关键材料。本项目不覆盖它，只补充 active/resolved 状态和 Completion gate。
上游已经加入实验性的 token-budget fallback：在自动压缩阈值前预留一段 token，并用 developer prompt 给 Agent 最后一次主动保全状态的机会。这个机制会改变压缩时机并增加一次采样或工具阶段，当前仍属于实验能力，因此本项目不自动启用它。这里采用的是同一设计原则：压缩前把可续作状态写清楚，但继续沿用 Codex 默认压缩时机。
相关上游入口：
- 新任务会在
startup读取当前 Hook 文件，不需要为每个任务重启应用。 - 已进入任务历史的旧 developer message 不会因磁盘文件变化而被立即删除。
- 旧任务下一次压缩后会收到新的
compact注入，但已经生成的那一次摘要无法被倒改。 - 若要严格验证新规则，请创建新任务；不要只凭当前长任务中的旧上下文判断安装是否生效。
- 任务中途切换模型不会撤回已进入历史的旧 developer context；需要严格模型隔离时请新建任务。
更早版本曾经：
- 在静态模型目录中追加
## Compaction continuity； - 使用完整
root_agent_usage_hint_text； - 通过 Hook 追加自定义子 Agent 编排。
当前版本只保留压缩连续性 Hook。安装器会自动移除它管理的旧子 Agent overlay，但不会自动改写 config.toml 或静态模型目录，因为这些文件可能包含其他用户配置。verify --strict-legacy 会报告旧 root 或模型目录覆盖，交给 Agent 逐项备份、核对和移除。
自动安装器是推荐方式。人工审计时：
- 把
hooks/session_start_overlay.py安装到$CODEX_HOME/hooks/codex-long-task-continuity.py。 - 把
prompts/compaction-continuity.md安装到$CODEX_HOME/prompt-overlays/。 - 若现有本项目 Hook 确实引用旧的
subagent-orchestration.md，先把该文件复制到带时间戳的备份目录并记录 SHA-256，再删除活动文件；无法确认所有权时保留并报告。 - 结构化读取现有
hooks.json，只合并上面的SessionStartgroup。 - Hook 脚本设为
0700，提示词和hooks.json设为0600；Windows 忽略 POSIX mode。 - 打开
/hooks审查并信任。
不要用字符串拼接修改 JSON，也不要用示例覆盖现有 hooks.json。
python3 install.py uninstall卸载前也会创建备份。恢复任意一次安装或卸载前状态：
python3 install.py restore "$CODEX_HOME/backups/codex-long-task-continuity-<timestamp>-<action>"恢复会校验 manifest、目标路径、权限和 SHA-256，并拒绝写入 manifest 所属 Codex Home 之外。
仓库测试只使用临时 Codex Home，不访问真实 ~/.codex：
python3 -m py_compile install.py hooks/session_start_overlay.py tests/test_install.py
python3 -m unittest discover -s tests -v测试覆盖安装、升级删除旧子 Agent overlay、幂等性、模型范围、Hook 保留、卸载、备份恢复、越界防护和旧覆盖检测。
本仓库使用 Apache License 2.0。它是独立项目，不是 OpenAI 官方组件；OpenAI 和 Codex 商标归其各自权利人所有。