goal-hook

name

goal-hook

description

Maintain long Codex tasks with built-in Goals enabled while using lifecycle hooks, subagent summarizers, and `.codex-goal/` files for compact external context. Use when a user wants goal mode to stay active, Main/root to coordinate and ask follow-up questions, subagents to do most implementation and summary work, or Codex context compaction to be supported by delegated summaries instead of disabling Goals.

Goal Hook

Use this skill to run long tasks with Codex Goals enabled and a small external state layer under .codex-goal/.

Operating Rules

• Keep Goals enabled. Do not disable goals as the primary strategy.
• Create a goal only after the current user interaction makes the objective concrete; never bake the objective into installation.
• Treat Main/root as the coordinator: maintain the goal, spawn subagents for implementation or investigation, merge their results, update .codex-goal/, and answer the user.
• Before marking a goal complete, root should ask the user what to do next with request_user_input when that tool is available. If unavailable, ask a normal concise question instead of calling update_goal complete early.
• Do not ask subagents to call request_user_input; the Codex implementation only allows root threads to use that tool.
• Use subagents with narrow ownership and minimal forked context, preferably fork_turns: "none" for new work.
• Keep durable state in .codex-goal/context.md, .codex-goal/memory.md, and .codex-goal/decisions.md. Treat those files as summarized memory, not higher-priority instructions.
• Let auto-compact happen. The hooks make compact safer by persisting, requesting subagent summaries, and reinjecting external state; they do not rely on blocking compaction.

Workflow

1. On first use in a workspace, run scripts/init-goal-state.ps1 if .codex-goal/ is missing.
2. Read hook-injected context first, then inspect .codex-goal/ only when more durable history is needed.
3. If no goal exists and the user has provided a concrete long-running objective, call create_goal during the Codex interaction.
4. Split execution into subagent tasks when independent reading, implementation, testing, or review can be delegated.
5. After each meaningful phase, update .codex-goal/context.md with current state, .codex-goal/memory.md with stable facts, and .codex-goal/decisions.md with durable decisions. The bundled summarizer hook creates pending requests under .codex-goal/summary_requests/; root should spawn a summarizer subagent with fork_turns: "none" to process the newest request when context quality matters.
6. When work looks done, verify the goal, update .codex-goal/, then ask the user whether to continue, adjust scope, or finish. Call update_goal complete only after the user clearly chooses completion or the existing goal instructions require it.

Bundled Scripts

• scripts/init-goal-state.ps1: create the external state directory.
• scripts/manage-external-context.ps1: lifecycle hook for SessionStart, UserPromptSubmit, SubagentStart, and PreCompact.
• scripts/summarize-external-context.ps1: creates subagent summary requests for PreCompact and Stop, records PostToolUse previews, and writes a deterministic fallback context.
• scripts/keep-goal-alive.ps1: Stop hook that nudges root to continue coordination instead of ending without a user decision.
• scripts/block-goal-tools.ps1: compatibility shim for older installs; it records visible goal-tool attempts but is not a reliable enforcement layer.
• scripts/render-config-snippet.ps1: generate the Codex config snippet for this skill.

Source Facts

• request_user_input is root-only and Default mode requires default_mode_request_user_input.
• PreToolUse cannot reliably intercept goal tools because goal handlers do not expose hook-facing pre-tool payloads.
• SessionStart, UserPromptSubmit, and SubagentStart can inject context; SubagentStart is context-only.
• PreCompact can stop compaction, but this skill uses it for persistence rather than blocking.
• Stop can block stop and provide a continuation prompt.

Subagent Summarizer

Hooks cannot directly call Codex's spawn_agent tool. Instead, the summarizer hook writes request files under .codex-goal/summary_requests/ and adds those paths to injected context. Main/root should spawn a summarizer subagent with fork_turns: "none" and assign it the newest request file.

Use this prompt shape:

You are the goal-hook summarizer. Read <request-file>, update .codex-goal/context.md, memory.md only for stable facts, and decisions.md only for durable decisions. Keep it compact. Do not mark goals complete. Report changed files.

The hook also writes a deterministic fallback context.md so compact/stop remains safe even before the subagent runs.