Astra-97/astra-codex-skills

Safe Context Forge

Use the installed Stop hook to detect the 80% boundary for the exact active thread, then create a genuinely new persistent thread with codex exec --json. Do not use codex fork: it copies the full source context and therefore does not free context space. The hook only schedules one model-visible continuation; the agent performs the reviewed handoff.

Workflow

1. If invoked by the Stop hook, use the complete session UUID in its continuation prompt. Otherwise obtain the UUID from current App/thread metadata. Never infer it from the newest rollout file.

2. Inspect only that session:

   py -3 scripts\safe_context_forge.py inspect --session-id <UUID>
   

3. Stop if threshold_reached is false. Context usage is the latest last_token_usage.total_tokens / model_context_window, not cumulative total_token_usage.

4. Tell the user that the automatic handoff is starting. Build a short private JSON handoff containing unfinished work, critical decisions, verification results, risks, and the next action. Do not paste transcript events, credentials, private URLs, auth headers, raw tool output, file contents, absolute paths, or filenames. See handoff-schema.md.

5. Run preparation, dry-run reporting, source fingerprint verification, and apply inside one script process. This matters because a separate tool result would append to the source transcript and correctly make an earlier artifact stale:

   py -3 scripts\safe_context_forge.py run --session-id <UUID> --handoff <handoff.json> --apply --confirm-session <UUID>
   

6. For manual inspection without creating a thread, omit --apply. The default is dry-run and leaves the private artifact path in its output:

   py -3 scripts\safe_context_forge.py run --session-id <UUID> --handoff <handoff.json>
   

7. Verify the new thread emits thread.started, replies exactly forge-ready, and is promoted for Desktop display. If it fails, keep using the old thread; failed candidates remain non-Desktop or are moved to quarantine.

Guardrails

• Require an explicit full UUID for every operation. Refuse duplicate matches.
• Keep dry-run as the default. Do not use --last or file modification time as identity.
• Never stop the App, modify a rollout, switch an active-thread pointer, or delete a source/backup.
• Keep the Stop hook in ~/.codex/hooks.json; never replace the existing notify command in config.toml.
• Honor stop_hook_active: the hook may request only one continuation, preventing a loop.
• Treat ~/.codex/safe-context-forge/completed/<source-session>.json as the one-shot marker. Never forge a marked source again automatically.
• Re-run inspect immediately before applying if the thread has continued substantially.
• Treat generated artifacts as sensitive and delete them after successful acknowledgement if the user authorizes cleanup.

Read environment-notes.md only when compatibility or automation behavior needs explanation. The user must review and trust the installed hook once in /hooks; until then Codex skips it.