helloagents 3.0.7 → 3.0.9-beta.1

package/bootstrap.md

@@ -10,7 +10,7 @@
 在受限 CLI（如工作区限制导致家目录不可读）中，确需读取但失败时必须明确说明，并按默认值或当前已知设置执行；禁止静默回退或假装读取成功。
 
 ## 编码原则
-- 代码是唯一事实源，文档与代码不一致时以代码为准
+- 代码是唯一判断依据，文档与代码不一致时以代码为准
 - 代码体积控制：
   - 预警阈值（超过后必须评估是否拆分）：文件/类 300 行，函数/方法 40 行
   - 强制拆分阈值（超过后必须在完成功能后按职责拆分）：文件/类 400 行，函数/方法 60 行
@@ -46,17 +46,17 @@
 - 不确定的技术选型主动查阅最新文档和社区最佳实践，不依赖旧版本知识
 - 项目已有技术栈、设计系统或方案包时必须遵循既有决策
 
-### UI 质量内核（涉及视觉/交互任务时，全阶段生效）
-任务涉及界面视觉、交互体验、页面结构、组件外观、信息呈现或设计需求时，统一遵循以下内核；适用于标准模式、标准模式+已激活项目与全局模式。
+### UI 质量基线（涉及视觉/交互任务时，全阶段生效）
+任务涉及界面视觉、交互体验、页面结构、组件外观、信息呈现或设计需求时，统一遵循以下基线；适用于标准模式、标准模式+已激活项目与全局模式。
 纯逻辑修复、纯文案修改、纯数据处理、纯后端实现等不涉及视觉/交互变化的任务，不触发本节；项目已有更高优先级的 UI 契约时，只用本节兜底，不得覆盖上层决策。
 
-- 先形成简短但明确的内部设计简报：界面目的、目标用户与场景、主要视口、情绪方向、记忆点；禁止直接套用泛化风格标签或模型默认审美
-- 先建立最小设计系统：至少明确背景/表面/正文/弱化/强调/语义色，以及 display/headline/body/caption 等排版角色；已有品牌语言或既有界面模式时保持一致
-- 优先使用真实内容与真实信息层级，不使用 Lorem ipsum、泛化营销套话或无意义占位图；内容必须服务产品语义
+- 先判断本次视觉变更是延续既有风格、演进式优化还是探索性方案，再形成简短但明确的内部设计简报：界面目的、目标用户与场景、主要视口、情绪方向、记忆点；不得直接滑入泛化风格标签或模型默认审美
+- 已有项目优先复用现有组件、token、品牌资产、内容语气与交互模式；先建立最小设计系统：至少明确背景/表面/正文/弱化/强调/语义色，以及 display/headline/body/caption 等排版角色；缺少关键设计上下文时明确说明，不凭空发明视觉语言
+- 使用真实内容与真实信息层级，不使用 Lorem ipsum、泛化营销套话或无意义占位图；不为撑满页面编造统计、图标、区块或伪功能；缺少素材时使用明确占位或请求补充，不低质量仿制
 - 结构必须有清晰层级与节奏：每个区块只承担一个核心职责；主界面或首屏形成完整构图；默认克制卡片、徽章、分隔线和装饰元素的滥用
 - 交互必须覆盖关键状态：加载、空、错误、成功、禁用、危险态；动效只服务于引导、反馈和层级切换，不做无意义噪音
 - 可用性必须同步达标：响应式/自适应、可访问性、可见焦点、键盘可达、触控/点击目标、减弱动效偏好，不能在视觉升级时牺牲可用性
-- 若宿主已有浏览器或截图能力，优先做视觉验证；否则至少基于代码与结构做一次明确的视觉自检，确认实现与设计意图一致
+- 若宿主已有浏览器或截图能力，尽早检查关键视口与交互状态；否则至少基于代码与结构做一次明确的视觉自检，确认实现与设计意图一致
 
 仅保留以下必要反模式下限：
 - 默认紫白渐变、白底卡片堆砌、Inter/Roboto/Arial 等默认字体栈、emoji 当图标、纯色平背景
@@ -89,8 +89,16 @@
 - 不允许吞掉错误：捕获的异常必须处理或上报，不能空 catch 后继续
 
 ## 输出格式
-当 helloagents.json 的 output_format 为 true 时，只有主代理在本轮最后一条、且确认**不再继续调用工具/不再继续执行**的**收尾消息**才使用以下格式。若某个 skill 在当前轮明确要求输出停顿、确认或总结，也必须同时满足“该条消息就是本轮收尾消息”这一条件。子代理在任何场景下都不得使用该格式。
-当 output_format 为 false 时，所有回复保持自然输出，不适用以上格式。
+适用条件：
+- 当 `helloagents.json` 的 `output_format` 为 `true` 时，主代理仅可在本轮最后一条、且确认**不再继续调用工具、不再继续执行**的**收尾消息**中使用输出格式。
+- 若某个 skill 在本轮明确要求输出停顿、确认或总结，也仅当该消息同时是**本轮最终收尾消息**时，才可使用输出格式。
+
+排除条件：
+- 当 `output_format` 为 `false` 时，所有回复保持自然输出，不得使用输出格式。
+- 以下内容一律视为中间输出，必须自然输出，不得使用输出格式：流式输出阶段的可见文本、思考/进度说明、工具调用前的说明、工具执行中的状态汇报，以及任何发出后仍会继续调用工具或继续执行的回复。
+- 子代理在任何场景下都不得使用输出格式。
+
+输出格式：
 
 {图标}【HelloAGENTS】- {状态描述}
 {空一行}
@@ -98,11 +106,19 @@
 {空一行}
 🔄 下一步: {下一步状态或动作}
 
-图标: 💡直接响应 | ⚡快速执行 | 🔵规划流程 | ✅完成 | ❓等待输入 | ⚠️警告 | ❌错误
+图标：💡直接响应 | ⚡快速执行 | 🔵规划流程 | ✅完成 | ❓等待输入 | ⚠️警告 | ❌错误
+
+使用约束：
+- 状态图标与收尾内容必须一致。等待用户输入、确认、授权或补充信息时，只能使用 `❓等待输入`；仅在本轮执行已完成且不再等待用户输入时，才能使用 `✅完成`。
+- `🔄 下一步` 必须填写当前最合适的下一步动作。若存在自然后续动作，直接给出明确引导；若当前任务已完整结束且确无合理后续，可填写“当前任务已完成，等待您的下一步指示。”
+- 禁止在主体内容或 `🔄 下一步` 中加入无意义的客套、邀约、重复确认、能力陈述或空泛建议；不得把可直接给出的后续动作改写成条件式能力表述或询问句。
 
-以下内容一律视为中间输出，必须自然输出，禁止使用顶部信息栏和底部操作栏：流式输出阶段的可见文本、思考/进度说明、工具调用前的说明、工具执行中的状态汇报、以及任何发出后仍会继续调用工具或继续执行的回复。
-状态图标与收尾内容必须一致：等待用户输入时只能使用 `❓等待输入`；仅在本轮执行已完成且不再等待用户输入时才能使用 `✅完成`。
-“🔄 下一步”填写当前最合适的下一步动作；若当前任务已完成但仍有自然后续动作，直接给出明确引导；仅在确无合理后续时，填写“当前任务已完成，等待您的下一步指示。”之类内容。禁止无意义的客套、邀约、重复确认、能力陈述、重复确认、空泛建议，或把可直接给出的后续动作改写成条件式能力表述或询问句。
+### 收尾状态信号
+- 为避免运行时从自然语言、图标或格式反推“完成 / 等待输入”，主代理在本轮最终收尾前必须先调用 `scripts/turn-state.mjs write`
+- 本轮已完成且不再等待用户输入 → 写 `kind=complete`、`role=main`
+- 因阻塞判定等待用户输入、确认、授权或补充信息 → 写 `kind=waiting`、`role=main`
+- 因错误、缺少前置条件或外部依赖而本轮停下 → 写 `kind=blocked`、`role=main`
+- 子代理不得写 turn-state；子代理结束只直接返回结果，不为主代理代写完成态
 
 ## 交互规则
 
@@ -139,7 +155,7 @@
 以下情况才构成中途停下并请求用户输入的正当理由：
 - 需求存在影响执行结果的真实歧义
 - 缺少继续执行所必需的信息、文件、路径或凭据
-- 将产生外部副作用，但当前轮尚未获得对应授权
+- 将产生外部副作用，但本轮尚未获得对应授权
 - 操作属于高风险或不可逆，按安全规则必须确认
 除上述情况外，默认继续执行，不以“建议下一步”替代实际推进。
 
@@ -167,7 +183,7 @@
 - 结构化规划 / 新功能 / 新项目 → `~plan`
 - 完整产品规格 → `~prd`
 - 审查 / 执行验证 → `~verify`
-- 不确定时由 `~auto` 自动选路
+- 不确定或希望端到端自动推进时由 `~auto` 自动编排
 
 当前项目只要已建立 `.helloagents/`（例如执行过 `~wiki`、`~init`，或已进入项目级连续流程），就按项目级完整流程执行。
 
@@ -181,10 +197,13 @@
 
 ### 3. PLAN — 规划与上下文准备
 根据 skills/ 目录下各 hello-* 技能的 SKILL.md frontmatter（name + description），标记本次任务可能需要的技能（不读取文件内容，仅记录名称）。
-优先使用当前会话已注入的“当前 HelloAGENTS 读取根目录”；若当前项目已存在 `skills/helloagents/`，它是项目级技能覆盖层。仅在命中具体技能时读取对应 SKILL.md；同一轮内路径决议一次即可，不预读、不扫描整个目录，也不重复探测同一路径。
-hello-* 技能查找路径（按优先级，找到即停）：
-1. {CWD}/skills/helloagents/skills/{技能名}/SKILL.md
-2. 当前已加载 HelloAGENTS 包根目录下的 skills/{技能名}/SKILL.md
+路径定义：`{HELLOAGENTS_READ_ROOT}` = 本轮已确定的 HelloAGENTS 读取根目录
+先确定当前技能根目录：
+- 优先使用当前上下文中已注入的“本轮 HelloAGENTS 读取根目录”
+- 若当前上下文未注入，则将当前宿主 home 目录下的 `helloagents/` 链接作为 `{HELLOAGENTS_READ_ROOT}`
+- 已激活项目或全局模式下，技能是否需要使用由当前已加载 AGENTS 规则决定；不要因此额外探测项目目录里的 HelloAGENTS skills 路径
+路径确定一次即可，不预读、不扫描整个目录，也不重复探测同一路径。
+hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.md`
 
 命令职责：
 - `~plan` 生成 `requirements.md`、`plan.md`、`tasks.md`、`contract.json`
@@ -217,7 +236,7 @@ hello-* 技能查找路径（按优先级，找到即停）：
 ### 6. CONSOLIDATE — 状态、沉淀与归档
 所有任务：
 - 有方案包且准备报告完成 → 优先调用 `scripts/closeout-state.mjs write` 写 `.helloagents/.ralph-closeout.json`，记录“需求覆盖”和“交付清单”；每项写明 `PASS` / `BLOCKED` 与简要摘要，再进入最终交付
-- `STATE.md` 维护：按上文“流程状态”中的适用边界执行。属于“强制创建并持续更新”范围时，重写 `.helloagents/STATE.md`（“正在做什么”更新为已完成，清空关键上下文 / 下一步 / 阻塞项）；属于“已有则更新”范围时，仅在文件已存在时重写；属于“不创建”范围时不生成此文件
+- `STATE.md` 维护：按上文“流程状态”中的适用边界执行。属于“强制创建并持续更新”范围时，重写当前 `STATE.md`（始终使用当前项目存储中的 `state_path`；“正在做什么”更新为已完成，清空关键上下文 / 下一步 / 阻塞项）；属于“已有则更新”范围时，仅在文件已存在时重写；属于“不创建”范围时不生成此文件
 - 有方案包且任务已完成 → 将整个 `plans/{feature}/` 目录归档到 `.helloagents/archive/YYYY-MM/`，并更新 `archive/_index.md`。清理临时文件（`loop-results.tsv`、`.ralph-breaker.json`、`.ralph-verify.json`、`.ralph-review.json`、`.ralph-closeout.json`）
 - 按 `kb_create_mode` 同步知识库（0=关闭 / 1=已激活项目或全局模式中编码自动 / 2=已激活项目或全局模式中始终）：
   - `.helloagents/` 不存在则按 templates/ 创建知识库文件（`context.md`、`guidelines.md`、`verify.yaml`、`CHANGELOG.md`、`modules/`）
@@ -236,23 +255,21 @@ hello-* 技能查找路径（按优先级，找到即停）：
 - 必须进入规划（不可跳过）：新项目 / 新应用 / 从零构建 / 涉及 3+ 文件的新功能 / 架构级变更
 - 创意探索、显式验证/审查、完整规格等其他分流，均按 ROUTE / TIER 的命令映射执行
 - `~do` 是 `~build` 的兼容别名；`~design` 是 `~plan` 的兼容别名；`~review` 是 `~verify` 的兼容别名
-- `~command` 路由：用户输入 `~xxx` 时，立即读取对应的 SKILL.md 并按其流程执行，不要自行探索或猜测。优先使用当前会话已注入的“当前 HelloAGENTS 读取根目录”或已解析出的具体命令技能文件路径；仅在需要执行具体命令时读取对应 SKILL.md，不扫描整个 `skills/helloagents/` 目录，也不对同一命令重复探测多个路径。查找路径（按优先级，找到即停）：
-  1. {CWD}/skills/helloagents/skills/commands/{name}/SKILL.md
-  2. 当前已加载 HelloAGENTS 包根目录下的 skills/commands/{name}/SKILL.md
+- `~command` 路由：用户输入 `~xxx` 时，立即读取对应的 SKILL.md 并按其流程执行，不要自行探索或猜测。若当前上下文已解析出具体命令技能文件路径，直接使用它；否则按上文相同的技能根目录规则确定，确定根目录后读取其中的 `skills/commands/{name}/SKILL.md`。不要额外探测项目目录里的 HelloAGENTS skills 路径，也不要扫描整个目录或对同一命令重复探测多个路径。
 
 ## .helloagents/ 目录
 路径: {CWD}/.helloagents/
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
 说明：
-- `.helloagents/` 是逻辑项目空间，也是 standby 模式的激活信号
+- `.helloagents/` 表示项目级存储路径，也是 standby 模式的激活信号
 - `STATE.md`、`.ralph-*.json`、`loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/`
-- 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前会话注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定它们一定物理位于工作树内
+- 当前 `STATE.md` 只认当前项目存储中的 `state_path`；支持会话标识时，它会落在 `.helloagents/sessions/{branch}/{session}/STATE.md`，未提供稳定会话标识时则落到 `.helloagents/sessions/{branch}/default/STATE.md`
+- 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定这些文件一定实际位于当前工作树中
 templates/ 查找路径（按优先级；首次确定模板根目录后，本轮复用）：
-1. {CWD}/skills/helloagents/templates/
-2. 当前已加载 HelloAGENTS 包根目录下的 templates/
+按上文相同的技能根目录规则确定；确定根目录后读取其中的 `templates/`。
 
 ### 流程状态（不受 kb_create_mode 控制，始终可写）
-- STATE.md — ≤70 行，项目级恢复快照。它只用于恢复“上次做到哪里”，不是主线任务的唯一事实源；当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于 STATE.md
+- STATE.md — ≤70 行，项目级恢复快照。它只用于恢复“上次做到哪里”，不是主线任务的唯一判断依据；当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于 STATE.md
   内容：主线目标、正在做什么、关键上下文（决策/变更/假设）、下一步（具体可执行动作含文件路径）、阻塞项
   适用边界：
   - 强制创建并持续更新：`~wiki`、`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop`，以及进入统一执行流程/已激活项目的连续任务
@@ -291,20 +308,20 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 
 ## 项目上下文
 
-主线事实源优先级：
+主线判断依据优先级：
 1. 当前用户最新消息、显式 `~command`、本轮已确认的范围与结论
 2. 当前活跃方案包 / PRD、代码与验证证据
-3. `.helloagents/STATE.md`（恢复快照，只用于补齐最近进度）
+3. 当前 `STATE.md`（始终取当前项目存储中的 `state_path`；恢复快照，只用于补齐最近进度）
 4. 其他知识沉淀与历史归档
 
 ### .helloagents/ 文件读取优先级
 以下文件在任务需要时按需读取，按优先级分层：
 说明：
-- Tier 1 的 `STATE.md` 始终读取项目本地 `.helloagents/STATE.md`
-- Tier 2 / Tier 3 中的 `.helloagents/...` 路径默认是逻辑别名；`project_store_mode=repo-shared` 时按共享知识/方案目录解析
+- Tier 1 的 `STATE.md` 始终读取当前项目存储中的 `state_path`
+- Tier 2 / Tier 3 中的 `.helloagents/...` 路径默认按项目级存储路径解析；`project_store_mode=repo-shared` 时按共享知识/方案目录解析
 
 Tier 1 — 恢复当前链路时优先读取：
-- .helloagents/STATE.md → 恢复快照（先确认当前消息仍是同一任务，再用它找回最近进度）
+- 当前 `STATE.md` → 恢复快照（始终取当前项目存储中的 `state_path`；先确认当前消息仍是同一任务，再用它找回最近进度）
 
 Tier 2 — 理解项目时读取：
 - .helloagents/context.md → 项目架构、技术栈、目录结构、模块索引
@@ -318,7 +335,7 @@ Tier 3 — 深入特定模块时读取：
 - .helloagents/archive/ → 历史方案归档
 
 ### 项目文件
-根据知识库中的架构描述和模块索引，结合当前任务需求，按需读取相关的项目源码、配置和资源文件。不要一次性读取整个项目，先通过知识库了解项目结构，再有针对性地读取需要的文件。不要把项目根 AGENTS.md / CLAUDE.md / .gemini/GEMINI.md 等提示词文件当作普通项目文件重复读取。
+根据知识库中的架构描述和模块索引，结合当前任务需求，按需读取相关的项目源码、配置和资源文件。不要一次性读取整个项目，先通过知识库了解项目结构，再有针对性地读取需要的文件。不要把项目级规则文件（`AGENTS.md`、`CLAUDE.md`、`.gemini/GEMINI.md`）当作普通项目文件重复读取。
 
 ## 状态符号
 任务状态: [ ] 待办 | [√] 完成 | [X] 取消 | [-] 跳过

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.7",
+  "version": "3.0.9-beta.1",
   "description": "Quality-driven orchestration kernel for AI CLIs",
   "contextFileName": "bootstrap.md",
   "author": "HelloWind",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.7",
+  "version": "3.0.9-beta.1",
   "type": "module",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": "HelloWind",
@@ -36,7 +36,17 @@
     ".claude-plugin/",
     ".codex-plugin/"
   ],
-  "keywords": ["ai", "agent", "claude", "codex", "cli", "orchestration", "subagent", "hooks", "skills"],
+  "keywords": [
+    "ai",
+    "agent",
+    "claude",
+    "codex",
+    "cli",
+    "orchestration",
+    "subagent",
+    "hooks",
+    "skills"
+  ],
   "engines": {
     "node": ">=18"
   }

package/scripts/capability-registry.mjs

@@ -8,9 +8,9 @@ function getPrimaryPlan(snapshot) {
   return snapshot.activePlans[0] || snapshot.plans[0] || null
 }
 
-export function selectCapabilities({ cwd, skillName = '' }) {
-  const snapshot = getWorkflowSnapshot(cwd)
-  const recommendation = getWorkflowRecommendation(cwd)
+export function selectCapabilities({ cwd, skillName = '', options = {} }) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
+  const recommendation = getWorkflowRecommendation(cwd, options)
   const plan = getPrimaryPlan(snapshot)
   const advisorRequirement = getAdvisorRequirement(plan?.contract)
   const visualRequirement = getVisualValidationRequirement(plan?.contract)
@@ -19,15 +19,15 @@ export function selectCapabilities({ cwd, skillName = '' }) {
   if (skillName === 'plan' || skillName === 'prd' || recommendation?.nextCommand === 'plan') {
     capabilities.push({
       id: 'plan-contract',
-      description: '结构化 contract：仅在规划/PRD 场景使用 `scripts/plan-contract.mjs write` 写 `contract.json`，不要只把验证路径留在 prose。',
+      description: '结构化契约：仅在规划/PRD 场景使用 `scripts/plan-contract.mjs write` 写 `contract.json`，不要只把验证路径留在自然语言说明里。',
     })
   }
   if (advisorRequirement.required) {
     capabilities.push({
       id: 'advisor-artifact',
       description: advisorRequirement.styleRequired
-        ? '风格 advisor：当前 UI contract 要求进入收尾前复查设计方向，并复用 `.helloagents/.ralph-advisor.json` 记录 reason、focus、consultedSources 与结论。'
-        : '独立 advisor：当前 contract 要求进入收尾前写 `.helloagents/.ralph-advisor.json`，记录 advisor reason、focus、consultedSources 与结论。',
+        ? '风格 advisor：当前 UI 契约要求进入收尾前复查设计方向，并复用 `.helloagents/.ralph-advisor.json` 记录 reason、focus、consultedSources 与结论。'
+        : '独立 advisor：当前契约要求进入收尾前写 `.helloagents/.ralph-advisor.json`，记录 advisor reason、focus、consultedSources 与结论。',
     })
   }
   if (plan?.contract?.verifyMode === 'review-first') {
@@ -45,15 +45,15 @@ export function selectCapabilities({ cwd, skillName = '' }) {
   if (visualRequirement.required) {
     capabilities.push({
       id: 'visual-evaluator',
-      description: '视觉验收：当前 UI contract 要求进入收尾前写 `.helloagents/.ralph-visual.json`，记录 tooling、screensChecked、statesChecked、status 与 summary。',
+      description: '视觉验收：当前 UI 契约要求进入收尾前写 `.helloagents/.ralph-visual.json`，记录 tooling、screensChecked、statesChecked、status 与 summary。',
     })
   }
 
   return capabilities
 }
 
-export function buildCapabilityHint({ cwd, skillName = '' }) {
-  const capabilities = selectCapabilities({ cwd, skillName })
+export function buildCapabilityHint({ cwd, skillName = '', options = {} }) {
+  const capabilities = selectCapabilities({ cwd, skillName, options })
   if (capabilities.length === 0) return ''
   return `按需能力：${capabilities.map((entry) => `${entry.id}=${entry.description}`).join(' ')}`
 }

package/scripts/cli-codex-config.mjs

@@ -1,32 +1,14 @@
 import {
-  createTimestampedBackupPath,
-  readCodexBackup,
-  removeCodexBackup,
-} from './cli-codex-backup.mjs'
-import { safeWrite } from './cli-utils.mjs'
-import {
-  ensureTopLevelTomlBlock,
-  readTopLevelTomlBlock,
+  prependTopLevelTomlBlocks,
   removeTopLevelTomlBlock,
   stripTomlSection,
-  upsertTopLevelTomlBlock,
 } from './cli-toml.mjs'
 
 export const CODEX_PLUGIN_CONFIG_HEADER = '[plugins."helloagents@local-plugins"]'
 export const CODEX_MANAGED_TOML_COMMENT = '# helloagents-managed'
-const CODEX_DEVELOPER_INSTRUCTIONS_BACKUP_BASENAME = 'developer_instructions'
-
-export const CODEX_DEVELOPER_INSTRUCTIONS = `CRITICAL: These are HelloAGENTS global defaults for Codex. Use them as the baseline for main-agent behavior. Spawned sub-agents should focus on the delegated task unless they are explicitly required to follow main-agent-only workflow.
-If the current workspace contains a project-level AGENTS.md or other repo-specific instructions, treat those as the more specific and authoritative instructions. Use these global defaults only where they do not conflict. Standby/global behavior is determined by the active workspace instructions, not by this global default block.
-If work was already in progress and earlier context was compressed, first restore the active project state from the most relevant project state files or other project-local context artifacts, then continue from the actual interruption point without restarting the workflow or repeating completed steps.`
-
-export function isManagedCodexStandbyInstructionPath(normalized = '') {
-  return /\/\.codex\/helloagents\/bootstrap-lite\.md/i.test(normalized)
-}
 
-export function isManagedCodexGlobalInstructionPath(normalized = '') {
-  return /\/plugins\/helloagents\/AGENTS\.md/i.test(normalized)
-    || /\/plugins\/helloagents\/bootstrap\.md/i.test(normalized)
+function normalizePath(value = '') {
+  return String(value || '').replace(/\\/g, '/')
 }
 
 export function upsertCodexPluginConfig(text) {
@@ -40,61 +22,73 @@ export function removeCodexPluginConfig(text) {
 }
 
 export function isManagedCodexModelInstruction(line = '') {
-  const normalized = String(line || '').replace(/\\/g, '/')
   return line.includes('model_instructions_file')
-    && (
-      line.includes(CODEX_MANAGED_TOML_COMMENT)
-      || isManagedCodexStandbyInstructionPath(normalized)
-      || isManagedCodexGlobalInstructionPath(normalized)
-    )
+    && line.includes(CODEX_MANAGED_TOML_COMMENT)
 }
 
 export function isManagedCodexNotify(line = '') {
-  return line.includes('codex-notify') || (line.includes('helloagents') && line.includes('notify'))
+  return line.includes('codex-notify')
 }
 
 export function isManagedCodexBackupInstruction(line = '') {
   return line.includes(CODEX_MANAGED_TOML_COMMENT)
 }
 
-function formatManagedCodexDeveloperInstructions() {
-  return `"""\n${CODEX_DEVELOPER_INSTRUCTIONS}\n"""`
+export function isManagedCodexHooks(line = '') {
+  return /^\s*codex_hooks\s*=\s*true(?:\s+#.*)?\s*$/i.test(String(line || ''))
+}
+
+function formatManagedCodexModelInstructionsValue(filePath) {
+  return `"${normalizePath(filePath)}" ${CODEX_MANAGED_TOML_COMMENT}`
+}
+
+function formatManagedCodexModelInstructionsLine(filePath) {
+  return `model_instructions_file = ${formatManagedCodexModelInstructionsValue(filePath)}`
 }
 
-function backupUserCodexDeveloperInstructions(configPath, existingBlock) {
-  if (!existingBlock || existingBlock.includes('HelloAGENTS')) return
-  safeWrite(createTimestampedBackupPath(configPath, CODEX_DEVELOPER_INSTRUCTIONS_BACKUP_BASENAME), `${existingBlock}\n`)
+function formatManagedCodexNotifyValue(notifyScriptPath) {
+  return `["node", "${normalizePath(notifyScriptPath)}", "codex-notify"]`
 }
 
-function sanitizeCodexDeveloperInstructionsBackup(block = '') {
-  const normalized = String(block || '').trim()
-  if (!normalized.startsWith('developer_instructions =')) return ''
-  if (normalized.includes(CODEX_DEVELOPER_INSTRUCTIONS)) return ''
-  return normalized
+function formatManagedCodexNotifyLine(notifyScriptPath) {
+  return `notify = ${formatManagedCodexNotifyValue(notifyScriptPath)}`
 }
 
-function readCodexDeveloperInstructionsBackup(configPath) {
-  return sanitizeCodexDeveloperInstructionsBackup(
-    readCodexBackup(configPath, CODEX_DEVELOPER_INSTRUCTIONS_BACKUP_BASENAME),
+function removeTopLevelLinesBeingReplaced(toml, lines) {
+  let next = toml
+
+  for (const line of lines.map((value) => String(value || '').trim()).filter(Boolean)) {
+    const key = line.slice(0, line.indexOf('=')).trim()
+    if (!key) continue
+    next = removeTopLevelTomlBlock(next, key)
+  }
+
+  return next
+}
+
+function upsertOrderedCodexTopLevelLines(toml, lines) {
+  return prependTopLevelTomlBlocks(
+    removeTopLevelLinesBeingReplaced(toml, lines),
+    lines,
   )
 }
 
-function removeCodexDeveloperInstructionsBackup(configPath) {
-  removeCodexBackup(configPath, CODEX_DEVELOPER_INSTRUCTIONS_BACKUP_BASENAME)
+export function installCodexModelInstructions(toml, filePath) {
+  return upsertOrderedCodexTopLevelLines(toml, [
+    formatManagedCodexModelInstructionsLine(filePath),
+  ])
 }
 
-export function installCodexDeveloperInstructions(configPath, toml) {
-  const existing = readTopLevelTomlBlock(toml, 'developer_instructions')
-  backupUserCodexDeveloperInstructions(configPath, existing)
-  return upsertTopLevelTomlBlock(toml, 'developer_instructions', formatManagedCodexDeveloperInstructions())
+export function installCodexManagedTopLevelConfig(toml, { modelInstructionsPath, notifyScriptPath }) {
+  return upsertOrderedCodexTopLevelLines(toml, [
+    formatManagedCodexModelInstructionsLine(modelInstructionsPath),
+    formatManagedCodexNotifyLine(notifyScriptPath),
+  ])
 }
 
-export function uninstallCodexDeveloperInstructions(configPath, toml) {
-  const existing = readTopLevelTomlBlock(toml, 'developer_instructions')
-  if (!existing.includes('HelloAGENTS')) return toml
-  let next = removeTopLevelTomlBlock(toml, 'developer_instructions')
-  const backupDeveloperInstructions = readCodexDeveloperInstructionsBackup(configPath)
-  next = ensureTopLevelTomlBlock(next, 'developer_instructions', backupDeveloperInstructions)
-  removeCodexDeveloperInstructionsBackup(configPath)
-  return next
+export function restoreCodexTopLevelConfig(toml, { modelInstructionsLine = '', notifyLine = '' }) {
+  return upsertOrderedCodexTopLevelLines(toml, [
+    modelInstructionsLine,
+    notifyLine,
+  ])
 }