context-brake 1.0.0 → 1.1.0

package/README.md

@@ -56,7 +56,7 @@ Support levels come from each vendor's documentation, checked in September 2026.
 
 | Harness | Integration point | Support level | Main limitation |
 | :--- | :--- | :--- | :--- |
-| Claude Code (`claude-code`) | Hooks in `.claude/settings.json` | Full | Context usage is read from the session transcript, whose format is undocumented, with an estimate as fallback; the context window comes from the status line bridge, which `init` installs by default |
+| Claude Code (`claude-code`) | Hooks in `.claude/settings.json` | Full | Context usage is read from the session transcript, whose format is undocumented, with an estimate as fallback; the context window comes from the [mod](#claude-code-context-source) that `init` installs on Claude Code 2.1.287 or later, or from the status line bridge on older versions |
 | Codex CLI (`codex-cli`) | Hooks in `.codex/hooks.json` | Full | Context usage and window are read from the session rollout file, whose format is undocumented; falls back to an estimate |
 | Cursor (`cursor`) | Hooks in `.cursor/hooks.json` | Full | Context usage is only sent before compaction |
 | GitHub Copilot CLI (`github-copilot-cli`) | Hooks in `.github/hooks/*.json` | Full | Context usage is not exposed to hooks, so ContextBrake estimates it |
@@ -65,7 +65,7 @@ Support levels come from each vendor's documentation, checked in September 2026.
 | Oh-My-Pi (`oh-my-pi`) | Extensions in `.omp/extensions/` | Full | Restart takes one Enter on the prefilled `/context-brake-restart` |
 | Antigravity CLI (`antigravity-cli`) | Hooks in `.agents/hooks.json` | Partial | Telemetry is injected through `PreInvocation`, and `PostToolUse` accepts only empty output |
 
-Aider is not supported because it has no hook mechanism. The full capability matrix and its sources are in the [installation PRD](./tasks/prd-01-instalacao-deteccao-diagnostico/prd.md).
+Aider is not supported because it has no hook mechanism. The hook and plugin APIs behind each row, with their sources, are in the [harness research](./docs/research/harness-integrations.md).
 
 ---
 
@@ -110,16 +110,16 @@ npx context-brake init --yes
 npx context-brake doctor
 ```
 
-To have the agent save its state before a reset, pass your snapshot command, and optionally the command that resumes the work in the new session:
+To have the agent save its state before a reset, pass the name of your snapshot skill, and optionally the name of the skill that resumes the work in the new session:
 
 ```bash
-npx context-brake init --yes --snapshot-command "/sdd-snapshot" --resume-command "/sdd-orchestrate-flow"
+npx context-brake init --yes --snapshot-command sdd-snapshot --resume-command sdd-orchestrate-flow
 ```
 
 ### What `context-brake init` does:
 
 1. **Detects coding-agent harnesses:** Identifies Claude Code, Cursor, Codex CLI, GitHub Copilot CLI, Antigravity CLI, OpenCode, Pi, and Oh-My-Pi from repository signals and machine configuration.
-2. **Registers integrations safely:** Injects the appropriate hooks/plugins in each harness's own configuration, preserving user settings and comments, and installs the [status line bridge](#claude-code-status-line-bridge) for Claude Code.
+2. **Registers integrations safely:** Injects the appropriate hooks/plugins in each harness's own configuration, preserving user settings and comments, and, for Claude Code, installs the [mod that reads the context](#claude-code-context-source) or, on versions without mods, the [status line bridge](#claude-code-status-line-bridge).
 3. **Initializes config:** Creates `context-brake.config.json` with the telemetry limits and the `snapshot` section, and records the installed files in `.context-brake/manifest.json`.
 
 It does not touch instruction files such as `CLAUDE.md` and `AGENTS.md`. The only change it makes to your `.gitignore` is the marked block described in [Keeping ContextBrake Out of Git](#keeping-contextbrake-out-of-git). Runtime state lives in `.context-brake/runtime/`, which carries its own `.gitignore`.
@@ -134,7 +134,8 @@ npx context-brake init --interactive --dry-run
 ```
 
 - **When it starts:** only when both stdin and stdout are terminals and none of `--yes`, `--json`, or a configuration flag (`--harness`, `--exclude-harness`, any snapshot flag, `--debug`, `--statusline-bridge`, `--auto-restart`, `--max-restarts`, and their `--no-` forms) is given. Scripts, CI, and `--json` runs never see a prompt and behave exactly as before. `--interactive` without a terminal exits with code 64 and names the flags to use instead; combined with `--yes` or `--json` it is an argument error.
-- **Questions, in order:** the harnesses to configure (detected ones are marked with their support level; turning off a detected one excludes it, as `--exclude-harness` does), the snapshot command, its trigger zone and resume command (only when a command is set), restart on or off with the restart mode of each selected harness (only when one can restart), the consecutive-restart limit (only when restart is on), the Claude Code status line bridge (only when Claude Code is selected), and debug mode. Enter keeps the value shown in brackets, which is the current configuration or the default. An invalid answer prints its rule and asks again.
+- **Questions, in order:** the harnesses to configure (detected ones are marked with their support level; turning off a detected one excludes it, as `--exclude-harness` does), the snapshot command, its trigger (a zone or a percentage of the context window) and resume command (only when a command is set), restart on or off with the restart mode of each selected harness (only when one can restart), the consecutive-restart limit (only when restart is on), the Claude Code status line bridge (only when Claude Code is selected), and debug mode. Enter keeps the value shown in brackets, which is the current configuration or the default. An invalid answer prints its rule and asks again.
+- **Skill suggestions:** for the snapshot and the resume questions, the assistant looks at the skill folders of the selected harnesses in the project (for example `.claude/skills`, `.agents/skills`, `.cursor/skills`, `.github/skills`, `.opencode/skills`, `.pi/skills`, `.omp/skills`), reads only the top of each `SKILL.md` for its name and description, and lists the best matches first. A name containing `snapshot`, `handoff`, or `checkpoint` ranks first for the snapshot; `resume`, `continue`, `orchestrate`, `flow`, and the Portuguese `retomar`, `retomada`, `continuar` for the resume; the description counts less, and the skill chosen for the snapshot is never offered for the resume. The list shows the recommended skill, up to three alternatives, `type another`, and for the snapshot `none`, and says where each one was found (the resume skill can be changed here but only removed with `--no-snapshot-command`, which clears both skills). The suggestion is a hint, not a decision: nothing is chosen without your Enter, and when nothing matches (or a folder cannot be read) you get the plain text question. Only skills inside the project folders are read: not your user-level skills, plugin skills, `.claude/commands`, or folders above the project root. A run with `--yes` or any configuration flag reads no skill folder.
 - **Prompts:** on a terminal the questions use arrow keys, Space to mark, and Enter to confirm (a checkbox list for harnesses, yes or no for the switches, a list for the trigger zone and the restart limit, text fields for the commands). Set `CONTEXT_BRAKE_PLAIN_PROMPTS=1`, or run in a terminal with `TERM=dumb`, to get plain line-by-line questions instead; the questions and the resulting flags are the same.
 - **Summary and equivalent command:** before the plan, the assistant prints what you chose and the `context-brake init ...` command that reproduces it. Values with spaces or shell characters are single-quoted, and a value that contains a single quote is printed once for POSIX shells and once for PowerShell. Add `--yes` to repeat the setup without prompts; a command with no flags means nothing changes and starts the questions again on a terminal.
 - **Confirming and cancelling:** the assistant shows the usual plan and asks the usual single confirmation. Ctrl+C or the end of input at any prompt prints `Nothing was written.` and exits with code 0, like a declined confirmation. With `--dry-run` it shows the plan and writes nothing. Typed configuration flags passed together with `--interactive` are not used; only `--dry-run` is.
@@ -194,7 +195,7 @@ The files `init` creates belong to your machine and `init` can regenerate them,
 }
 ```
 
-`contextWindowCeiling` is the session's context budget: when the harness does not report the active model's window, zone percentages are computed against it, and the telemetry block shows `window=config`. A more accurate window comes from the harness (`window=harness`: Pi and Oh-My-Pi, Codex through the session rollout file, and Claude Code through the [status line bridge](#claude-code-status-line-bridge), which `init` installs by default) or, for the harnesses that report none (Cursor, GitHub Copilot, Antigravity, OpenCode), from a window you declare in `telemetry.declaredContextWindow` (`window=declared`). A declared window is ignored by Claude Code, Codex, Pi, and Oh-My-Pi, whose window comes from the harness. The optional `zones.greenMaxTurn` and `zones.yellowMaxTurn` must be set together, with `greenMaxTurn` lower; they raise the zone up to `RED` by turns.
+`contextWindowCeiling` is the session's context budget: when the harness does not report the active model's window, zone percentages are computed against it, and the telemetry block shows `window=config`. A more accurate window comes from the harness (`window=harness`: Pi and Oh-My-Pi, Codex through the session rollout file, and Claude Code through the [mod](#claude-code-context-source), or the [status line bridge](#claude-code-status-line-bridge) on versions without mods) or, for the harnesses that report none (Cursor, GitHub Copilot, Antigravity, OpenCode), from a window you declare in `telemetry.declaredContextWindow` (`window=declared`). A declared window is ignored by Claude Code, Codex, Pi, and Oh-My-Pi, whose window comes from the harness. The optional `zones.greenMaxTurn` and `zones.yellowMaxTurn` must be set together, with `greenMaxTurn` lower; they raise the zone up to `RED` by turns.
 
 ### Excluding a Harness
 
@@ -206,23 +207,34 @@ A configuration that still carries keys ContextBrake no longer reads (for exampl
 
 ### Snapshot and Resume Commands
 
-If your workflow saves session state with its own skill or command, as the SDD skills in this repository do, name it in the `snapshot` section:
+If your workflow saves session state with its own skill, as the SDD skills in this repository do, name it in the `snapshot` section. The value is the **bare skill name**, with no `/`, `$`, or `@`; each harness writes the invocation in its own form:
 
 ```json
 {
   "snapshot": {
     "triggerZone": "RED",
-    "command": "/sdd-snapshot",
-    "resumeCommand": "/sdd-orchestrate-flow"
+    "command": "sdd-snapshot",
+    "resumeCommand": "sdd-orchestrate-flow"
   }
 }
 ```
 
-- **`command`:** from `triggerZone` on (`RED` by default, or `YELLOW`), the telemetry action becomes `run "<command>", then end reply with [REQUEST_SESSION_RESET]`, and in `CRITICAL` it says `now`. ContextBrake never runs the command; it only passes the text to the agent, so the command can be a skill, a slash command, or a short instruction.
-- **`resumeCommand`:** after `/clear`, `/new`, or compaction, harnesses that inject context at session start add `[ContextBrake resume v1] Run "<resumeCommand>" before continuing.` A resume command requires a snapshot command.
+- **`command`:** from `triggerZone` on (`RED` by default, or `YELLOW`), the telemetry action becomes `run "<invocation>", then end reply with [REQUEST_SESSION_RESET]`, and in `CRITICAL` it says `now`. ContextBrake never runs the skill; it passes the invocation to the agent, written the way the harness that receives it invokes a skill.
+- **`resumeCommand`:** after `/clear`, `/new`, or compaction, harnesses that inject context at session start add `[ContextBrake resume v1] Run "<invocation>" before continuing.` A resume skill requires a snapshot skill.
+
+| Harness | Invocation of `sdd-snapshot` |
+| :--- | :--- |
+| Claude Code, Cursor, GitHub Copilot CLI | `/sdd-snapshot` |
+| Codex CLI | `$sdd-snapshot` |
+| Pi | `/skill:sdd-snapshot` |
+| Oh-My-Pi, OpenCode, Antigravity CLI | `use the sdd-snapshot skill` (these harnesses have no invocation form that works without extra setup) |
+
+A name is lowercase letters, digits, and single hyphens, up to 64 characters, optionally prefixed by a plugin name and a colon (`plugin:skill`). A value such as `/sdd-snapshot` is rejected with the bare name to use instead. `context-brake doctor` lists the invocation each active harness receives.
 - **Without a command:** the telemetry block only carries the generic actions in the [zone table](#-zones), with no reset request, and nothing is injected at session start.
 
-Set them with `init`: `--snapshot-command <text>`, `--resume-command <text>`, and `--snapshot-trigger <YELLOW|RED>`. `--no-snapshot-command` clears both commands and keeps the trigger zone. Each command is one line of at most 200 characters. In Git Bash on Windows, run `MSYS_NO_PATHCONV=1 npx context-brake init ...`, because Git Bash rewrites an argument that starts with `/`, such as `/sdd-snapshot`, into a Windows path. `context-brake doctor` shows the settings in effect, and `doctor --json` reports them under `snapshot`.
+- **`triggerPercentage`:** an optional whole number from 1 to 100 that replaces `triggerZone` as the trigger: the reset action starts once the context usage reaches that percentage, even in `GREEN` and below `activationThresholdPercentage` (the block is injected from that point on). `init` offers it in the trigger question and removes it when you pick a zone again.
+
+Set them with `init`: `--snapshot-command <skill>`, `--resume-command <skill>`, `--snapshot-trigger <YELLOW|RED>`, and `--snapshot-trigger-percentage <1-100>` (not together with `--snapshot-trigger`). `--no-snapshot-command` clears both skills and keeps the trigger. `context-brake doctor` shows the settings in effect, and `doctor --json` reports them under `snapshot`, with the invocation of each active harness under `snapshot.invocations`.
 
 ### Debug Mode
 
@@ -249,9 +261,13 @@ The agent copies that line instead of composing it. Nothing is written to instru
 
 `context-brake doctor` lists the repository's active sessions with their current context usage: percentage, tokens, window, zone, and whether the reading was measured or estimated. It also shows the time of each session's last activity. The data comes from the session ledger ContextBrake already keeps under `.context-brake/runtime/sessions/`, using the newest reading after the last reset, from the status line bridge or from the last tool call. ContextBrake cannot tell whether a harness process is still running. A session counts as active when its last recorded activity is within 30 minutes, and at most 10 sessions are listed. `doctor --json` reports them under `activeSessions`, and the list is omitted when no session is active.
 
+### Claude Code Context Source
+
+Claude Code sends the active model's context window only to the status line command and to mods, never to hooks. On Claude Code 2.1.287 or later, `init` installs a mod that publishes the window and the input tokens, so zones use the real window instead of `contextWindowCeiling` and `init` never touches your `statusLine`. The mod runs in the files under `.context-brake/claude-mod/` and registers itself in `.claude/settings.local.json`; it restarts nothing unless you also use `--auto-restart`. `init` reads the installed version with `claude --version`; when it cannot, or the version is older, it installs the status line bridge below instead. Running `init` again on a compatible version migrates an installed bridge: it restores the status line you had and removes the bridge script. `context-brake doctor` reports `contextWindow.source` (`mod`, `statusline`, or `contextWindowCeiling`) and `contextWindow.mod` (`absent`, `installed`, or `reporting`; `reporting` means a session of this repository has reported a reading at some point, with no freshness bound), and warns with `CONTEXT_MOD_SILENT` when the mod is installed but no session has reported yet (mods stay off under `disableAllHooks`, `--safe-mode`, `--bare`, an organization managed policy, and in Desktop WSL sessions).
+
 ### Claude Code Status Line Bridge
 
-Claude Code sends the active model's context window only to the status line command, never to hooks. The bridge reads it there, so zones in Claude Code use the real window instead of `contextWindowCeiling`. `init` installs it by default. To turn it back on after an opt-out:
+On Claude Code versions without mods, the bridge reads the context window from the status line command, so zones use the real window instead of `contextWindowCeiling`. `init` installs it there by default. To use it on any version, including after an opt-out:
 
 ```bash
 npx context-brake init --statusline-bridge
@@ -309,38 +325,12 @@ Each hook call has an internal deadline of 1.5 seconds; the session start event
 
 | Command | Options | Description |
 | :--- | :--- | :--- |
-| `context-brake init` | `--dry-run`, `--yes` (`-y`), `--json`, `--harness <id>`, `--exclude-harness <id>`, `--snapshot-command <text>`, `--snapshot-trigger <YELLOW\|RED>`, `--resume-command <text>`, `--no-snapshot-command`, `--debug`, `--no-debug`, `--statusline-bridge`, `--no-statusline-bridge`, `--auto-restart`, `--no-auto-restart`, `--max-restarts <1-10>`, `--interactive`, `--gitignore`, `--no-gitignore` | Detects harnesses, registers integrations, and creates or updates the configuration and the manifest. `--exclude-harness` turns a harness off persistently and `--harness` turns it back on. In a terminal with no other option, or with `--interactive`, it asks the [setup questions](#interactive-setup). |
+| `context-brake init` | `--dry-run`, `--yes` (`-y`), `--json`, `--harness <id>`, `--exclude-harness <id>`, `--snapshot-command <skill>`, `--snapshot-trigger <YELLOW\|RED>`, `--snapshot-trigger-percentage <1-100>`, `--resume-command <skill>`, `--no-snapshot-command`, `--debug`, `--no-debug`, `--statusline-bridge`, `--no-statusline-bridge`, `--auto-restart`, `--no-auto-restart`, `--max-restarts <1-10>`, `--interactive`, `--gitignore`, `--no-gitignore` | Detects harnesses, registers integrations, and creates or updates the configuration and the manifest. `--exclude-harness` turns a harness off persistently and `--harness` turns it back on. In a terminal with no other option, or with `--interactive`, it asks the [setup questions](#interactive-setup). |
 | `context-brake doctor` | `--json`, `--harness <id>` | Inspects integrations, configuration integrity, versions, support levels, missing capabilities, snapshot settings, and active sessions with their context usage, and measures overhead p95. |
 | `context-brake remove` | `--dry-run`, `--yes` (`-y`), `--json` | Uninstalls the integrations and deletes the configuration, the manifest, and the runtime files. |
 
 ---
 
-## 🧭 Roadmap
-
-| PRD | Scope | Status |
-| :--- | :--- | :--- |
-| [Installation, detection, and diagnostics](./tasks/prd-01-instalacao-deteccao-diagnostico/prd.md) | `init`, `doctor`, `remove`, harness support levels | Implemented |
-| [Installation follow-ups](./tasks/prd-01.1-pendencias-da-instalacao/prd.md) | Capabilities, overhead measurement, manifest, and installed assets | Implemented |
-| [Telemetry, zones, and brake](./tasks/prd-02-telemetria-zonas-e-freio/prd.md) | Turn counting, context measurement, zones | Implemented; the tool-call deny was removed by the single mode |
-| [Brake by measured usage](./tasks/prd-02.1-freio-por-uso-medido/prd.md) | Usage-only `CRITICAL`, optional turn limits, measured usage in Claude Code | Implemented |
-| [Claude Code context window](./tasks/prd-02.2-janela-de-contexto-do-claude-code/prd.md) | Status line bridge | Implemented |
-| [Plan, checkpoint, and boot](./tasks/prd-03-plano-checkpoint-e-boot/prd.md) | State files and boot summary | Superseded by the single mode |
-| [Automatic reset runner](./tasks/prd-04-runner-de-reinicio-automatico/prd.md) | Post-MVP runner | Superseded by the single mode |
-| [Release automation](./tasks/prd-05-automacao-de-release-e-publicacao/prd.md) | Automated release and npm publishing | Implemented |
-| [Delegated snapshot mode](./tasks/prd-06-modo-snapshot-delegado/prd.md) | Snapshot command without a task plan | Superseded by the single mode |
-| [Light mode](./tasks/prd-07-modo-leve/prd.md) | Telemetry only, and active-session usage in `doctor` | Superseded by the single mode |
-| [Debug mode](./tasks/prd-08-modo-debug/prd.md) | Usage line printed by the agent | Implemented |
-| [Brake with a trusted window](./tasks/prd-09-freio-com-janela-confiavel/prd.md) | Window origin and declared window | Implemented |
-| [Status line under PowerShell](./tasks/prd-10-statusline-powershell-e-modo-light/prd.md) | Shell-neutral bridge and debug line | Implemented |
-| [Automatic restart in Claude Code](./tasks/prd-11-reinicio-automatico-no-claude-code/prd.md) | Claude Code mod that clears and resumes the session | Implemented |
-| [Single mode](./tasks/prd-12-refatoracao-modo-leve-modo-unico/prd.md) | One mode with optional snapshot and resume commands, advisory brake | In progress |
-| [Fast test suite](./tasks/prd-13-refatoracao-modo-leve-testes-rapidos/prd.md) | Test budget | Planned |
-| [Restart and handoff across harnesses](./tasks/prd-14-refatoracao-modo-leve-reinicio-multi-harness/prd.md) | Automatic restart and markdown handoff beyond Claude Code | In progress |
-
-The PRDs are written in Portuguese, except the later ones.
-
----
-
 ## 🤝 Contributing
 
 This project follows Spec-Driven Development. Read [AGENTS.md](./AGENTS.md) and the PRD of the feature you are changing before opening a pull request.

package/dist/assets/runtime/antigravity-cli-hook.mjs

@@ -4,6 +4,14 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/core/services/skill-invocation.ts
+function sentenceInvocation(skill) {
+  return `use the ${skill} skill`;
+}
+
+// src/infrastructure/harnesses/antigravity-cli/skill-invocation.ts
+var ANTIGRAVITY_SKILL_INVOCATION = sentenceInvocation;
+
 // src/infrastructure/harnesses/common/runtime-support.ts
 import { realpath } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
@@ -18160,6 +18168,34 @@ var HARNESS_IDS = [
   "antigravity-cli"
 ];
 
+// src/core/contracts/skill-name.ts
+var MAX_SKILL_NAME_LENGTH = 64;
+var NAME_SEGMENT = "[a-z0-9]+(?:-[a-z0-9]+)*";
+var NAMESPACE_SEPARATOR = ":";
+var INVOCATION_CHARACTERS = ["/", "$", "@"];
+var MAX_QUALIFIED_LENGTH = MAX_SKILL_NAME_LENGTH * 2 + NAMESPACE_SEPARATOR.length;
+function segmentFits(end) {
+  return `(?=[^${NAMESPACE_SEPARATOR}]{1,${MAX_SKILL_NAME_LENGTH}}${end})`;
+}
+var PREFIX = `(?:${segmentFits(NAMESPACE_SEPARATOR)}${NAME_SEGMENT}${NAMESPACE_SEPARATOR})?`;
+var SKILL_NAME_PATTERN = new RegExp(`^${PREFIX}${segmentFits("$")}${NAME_SEGMENT}$`);
+var SHAPE_RULE = `lowercase letters, digits, and single hyphens, up to ${MAX_SKILL_NAME_LENGTH} characters, optionally prefixed by a plugin name and a colon`;
+function isSkillName(value) {
+  return SKILL_NAME_PATTERN.test(value);
+}
+function skillNameProblem(value) {
+  if (value === "") return "must not be empty";
+  if (isSkillName(value)) return null;
+  const bare = INVOCATION_CHARACTERS.includes(value.charAt(0)) ? value.slice(1) : null;
+  if (bare !== null && isSkillName(bare)) return `"${value}" is not a skill name; use the bare name ${bare}`;
+  return `"${value}" is not a skill name; use ${SHAPE_RULE}`;
+}
+var skillNameSchema = external_exports.string().check((ctx) => {
+  const message = skillNameProblem(ctx.value);
+  if (message !== null) ctx.issues.push({ code: "custom", input: ctx.value, message });
+});
+external_exports.globalRegistry.add(skillNameSchema, { pattern: SKILL_NAME_PATTERN.source, maxLength: MAX_QUALIFIED_LENGTH });
+
 // src/core/contracts/zones.ts
 var ZONES = ["GREEN", "YELLOW", "RED", "CRITICAL"];
 var USAGE_SOURCES = ["measured", "estimated"];
@@ -18183,15 +18219,8 @@ function uniqueCheck(message) {
     if (!isUnique(ctx.value)) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message });
   };
 }
-var MAX_AGENT_COMMAND_LENGTH = 200;
-var TRIMMED_RULE = "must not have leading or trailing whitespace";
 var RESUME_REQUIRES_COMMAND_RULE = "requires snapshot.command";
-var SINGLE_LINE_RULE = "must be a single line";
-var agentCommand = external_exports.string().check(external_exports.minLength(1), external_exports.maxLength(MAX_AGENT_COMMAND_LENGTH), (ctx) => {
-  if (ctx.value.trim() !== ctx.value) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message: TRIMMED_RULE });
-  if (/[\r\n]/.test(ctx.value)) addIssue(ctx, { code: "custom", path: [], input: ctx.value, message: SINGLE_LINE_RULE });
-});
-var snapshotSchema = external_exports.strictObject({ triggerZone: external_exports._default(external_exports.enum(SNAPSHOT_TRIGGER_ZONES), "RED"), command: external_exports.optional(agentCommand), resumeCommand: external_exports.optional(agentCommand) }).check((ctx) => {
+var snapshotSchema = external_exports.strictObject({ triggerZone: external_exports._default(external_exports.enum(SNAPSHOT_TRIGGER_ZONES), "RED"), triggerPercentage: external_exports.optional(external_exports.int().check(external_exports.minimum(1), external_exports.maximum(100))), command: external_exports.optional(skillNameSchema), resumeCommand: external_exports.optional(skillNameSchema) }).check((ctx) => {
   if (ctx.value.resumeCommand !== void 0 && ctx.value.command === void 0) addIssue(ctx, { code: "custom", path: ["resumeCommand"], input: ctx.value.resumeCommand, message: RESUME_REQUIRES_COMMAND_RULE });
 });
 var DEFAULT_SNAPSHOT = { triggerZone: "RED" };
@@ -18272,21 +18301,25 @@ var GENERIC_ACTIONS = {
   RED: "finish or pause the current unit and tell the user what remains",
   CRITICAL: "stop starting new work; tell the user what remains"
 };
-function zoneAction(zone, snapshot, mode = "off") {
-  if (zone === "GREEN" || !isAtOrAbove(zone, snapshot.triggerZone)) return GENERIC_ACTIONS[zone];
-  if (snapshot.command !== void 0) return snapshotAction(zone, snapshot.command);
-  if (mode !== "handoff") return GENERIC_ACTIONS[zone];
+function isResetDue(reading, snapshot) {
+  if (snapshot.triggerPercentage !== void 0) return reading.usagePercentage >= snapshot.triggerPercentage;
+  return reading.zone !== "GREEN" && isAtOrAbove(reading.zone, snapshot.triggerZone);
+}
+function zoneAction(zone, snapshot, options = {}) {
+  if (!isResetDue({ zone, usagePercentage: options.usagePercentage ?? 0 }, snapshot)) return GENERIC_ACTIONS[zone];
+  if (snapshot.command !== void 0) return snapshotAction(zone, (options.invoke ?? sentenceInvocation)(snapshot.command));
+  if ((options.mode ?? "off") !== "handoff") return GENERIC_ACTIONS[zone];
   return `save handoff to ${HANDOFF_PATH}, end reply with ${SESSION_RESET_SIGNAL}`;
 }
-function snapshotAction(zone, command) {
+function snapshotAction(zone, invocation) {
   const now = zone === "CRITICAL" ? " now" : "";
-  return `run "${command}"${now}, then end reply with ${SESSION_RESET_SIGNAL}`;
+  return `run "${invocation}"${now}, then end reply with ${SESSION_RESET_SIGNAL}`;
 }
 function handoffResumeText(archivedPath) {
   return `${RESUME_PREFIX} Read "${archivedPath}" and continue the previous work from it.`;
 }
-function resumeText(snapshot) {
-  return snapshot.resumeCommand === void 0 ? null : `${RESUME_PREFIX} Run "${snapshot.resumeCommand}" before continuing.`;
+function resumeText(snapshot, invoke = sentenceInvocation) {
+  return snapshot.resumeCommand === void 0 ? null : `${RESUME_PREFIX} Run "${invoke(snapshot.resumeCommand)}" before continuing.`;
 }
 function isAtOrAbove(zone, trigger) {
   return ZONES.indexOf(zone) >= ZONES.indexOf(trigger);
@@ -18331,7 +18364,7 @@ async function resolveFailure(input2) {
   return { kind: "neutral" };
 }
 function deadlineBootDecision(input2) {
-  const text = resumeText((input2.config ?? DEFAULT_CONFIG).snapshot);
+  const text = resumeText((input2.config ?? DEFAULT_CONFIG).snapshot, input2.descriptor?.skillInvocation);
   return text === null ? { kind: "neutral" } : { kind: "context", block: text };
 }
 async function recordRuntimeFailure(errors, record2) {
@@ -18442,7 +18475,7 @@ function isDebugModeInEffect(config2) {
 
 // src/core/services/injection-policy.ts
 function decideInjection(input2) {
-  if (input2.debug || input2.telemetry.injectionMode === "always") return true;
+  if (input2.debug || input2.resetDue === true || input2.telemetry.injectionMode === "always") return true;
   return input2.zone !== "GREEN" || input2.usagePercentage >= input2.telemetry.activationThresholdPercentage;
 }
 
@@ -18593,7 +18626,7 @@ async function handleSessionReset(options, event, hooks = {}) {
   if (!options.descriptor.capabilities.some((entry) => entry.id === "session_boot" && entry.state === "supported")) return NEUTRAL;
   if (event.reason === "compact" && !COMPACTION_BOOT_HARNESSES.includes(options.descriptor.harness)) return NEUTRAL;
   hooks.onPhase?.("guidance");
-  const text = resumeText(options.config.snapshot) ?? await claimHandoff(options, event.reason, hooks.deadline);
+  const text = resumeText(options.config.snapshot, options.descriptor.skillInvocation) ?? await claimHandoff(options, event.reason, hooks.deadline);
   return text === null ? NEUTRAL : { kind: "context", block: text };
 }
 async function claimHandoff(options, reason, deadline) {
@@ -18635,8 +18668,9 @@ async function handlePreInvocation(options, event, input2) {
   return telemetryDecision(options, summary.turns, readZone(options, { summary, turns: summary.turns, observedCharacters: 0, measured: input2.measured }));
 }
 async function telemetryDecision(options, turn, view) {
-  if (!decideInjection({ telemetry: options.config.telemetry, zone: view.zone, usagePercentage: view.percentage, debug: isDebugModeInEffect(options.config) })) return NEUTRAL2;
-  const action = zoneAction(view.zone, options.config.snapshot, restartMode(options.config));
+  const resetDue = isResetDue({ zone: view.zone, usagePercentage: view.percentage }, options.config.snapshot);
+  if (!decideInjection({ telemetry: options.config.telemetry, zone: view.zone, usagePercentage: view.percentage, debug: isDebugModeInEffect(options.config), resetDue })) return NEUTRAL2;
+  const action = zoneAction(view.zone, options.config.snapshot, { mode: restartMode(options.config), invoke: options.descriptor.skillInvocation, usagePercentage: view.percentage });
   return { kind: "context", block: renderTelemetryBlock({ turn, turnCeiling: redStartTurn(options.config.telemetry.zones), usagePercentage: view.percentage, usage: view.reading, zone: view.zone, action, debug: isDebugModeInEffect(options.config) }) };
 }
 async function handleResponseEnd(options, event) {
@@ -18670,6 +18704,17 @@ import { createHash } from "node:crypto";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join as join2, resolve as resolve3 } from "node:path";
 
+// src/core/contracts/context-reading.ts
+var RUNTIME_IGNORE_CONTENT = "*\n";
+var PERCENTAGE_MAXIMUM = 100;
+var contextReadingSchema = external_exports.strictObject({
+  v: external_exports.literal(1),
+  at: external_exports.string().check(external_exports.minLength(1)),
+  windowTokens: external_exports.nullable(external_exports.int().check(external_exports.positive())),
+  inputTokens: external_exports.nullable(external_exports.int().check(external_exports.nonnegative())),
+  usedPercentage: external_exports.nullable(external_exports.number().check(external_exports.gte(0), external_exports.lte(PERCENTAGE_MAXIMUM)))
+});
+
 // src/infrastructure/storage/runtime-state-files.ts
 import { readdir } from "node:fs/promises";
 import { join, relative, resolve as resolve2 } from "node:path";
@@ -18689,7 +18734,7 @@ async function listRuntimeStateFiles(root, readdirFn = readdir) {
 }
 
 // src/infrastructure/runtime/runtime-paths.ts
-var RUNTIME_GITIGNORE_CONTENT = "*\n";
+var RUNTIME_GITIGNORE_CONTENT = RUNTIME_IGNORE_CONTENT;
 var SESSIONS_DIR_NAME = "sessions";
 var LEDGER_FILE_EXTENSION = ".jsonl";
 var SESSIONS_RELATIVE_PREFIX = `${RUNTIME_STATE_RELATIVE_DIR}/${SESSIONS_DIR_NAME}/`;
@@ -19124,7 +19169,7 @@ var antigravityPayloadSchema = external_exports.looseObject({
 // src/infrastructure/harnesses/antigravity-cli/runtime.ts
 var HARNESS = "antigravity-cli";
 var ESTIMATION = { baselineTokens: 15e3, tokensPerTurn: 150 };
-var antigravityDescriptor = { harness: HARNESS, capabilities: ANTIGRAVITY_CAPABILITIES, estimation: ESTIMATION, newSessionCommand: null };
+var antigravityDescriptor = { harness: HARNESS, capabilities: ANTIGRAVITY_CAPABILITIES, estimation: ESTIMATION, newSessionCommand: null, skillInvocation: ANTIGRAVITY_SKILL_INVOCATION };
 function sessionOf(payload) {
   return { harness: HARNESS, sessionId: requireIdentifier(payload.conversationId), agentId: null };
 }