@reticlehq/init 3.6.0 → 3.8.0

package/dist/plan/stop-hook-step.js

@@ -1,12 +1,14 @@
 /**
- * `init --hooks`: the print-only Claude Code Stop hook, merged into `.claude/settings.json`.
+ * `init --hooks`: the Claude Code Stop hook, merged into `.claude/settings.json`.
  *
  * Opt-in, because it writes into a file the user and other tools own. When the agent stops without a
- * single claim having held, the hook prints one line saying so; it never blocks the agent. The line
- * itself is `reticle report --hook`, which reads the session journal on disk.
+ * single claim having held, the hook prints one line saying so and does not block. The line
+ * itself is `reticle report --hook`, which reads the session journal on disk. It blocks the stop in one
+ * case: a Harness drive the agent started still runs, so the agent stays to read its result.
  */
 import { RETICLE_NPM_PACKAGE } from '../version.js';
 import { StepStatus } from './plan-types.js';
+import { PROMPT_HOOK_AGENTS, PromptHookAgent, PromptHookStatus, installPromptHook, promptHookCommand, } from '../register/prompt-hooks.js';
 export const CLAUDE_SETTINGS_PATH = '.claude/settings.json';
 export const STOP_HOOK_COMMAND = `npx ${RETICLE_NPM_PACKAGE} report --hook`;
 const TITLE = 'Claude Code Stop hook';
@@ -36,14 +38,161 @@ export function stopHookStep(path, existing) {
     const hooks = isObject(settings['hooks']) ? settings['hooks'] : {};
     const stop = Array.isArray(hooks[STOP_EVENT]) ? hooks[STOP_EVENT] : [];
     if (JSON.stringify(stop).includes(STOP_HOOK_COMMAND)) {
-        return { title: TITLE, target: path, status: StepStatus.ALREADY, detail: 'hook already installed' };
+        return {
+            title: TITLE,
+            target: path,
+            status: StepStatus.ALREADY,
+            detail: 'hook already installed',
+        };
     }
     const merged = { ...settings, hooks: { ...hooks, [STOP_EVENT]: [...stop, HOOK_ENTRY] } };
     return {
         title: TITLE,
         target: path,
         status: StepStatus.APPLY,
-        detail: 'print one line when the agent stops without a claim that held; never blocks it',
+        detail: 'print one line when the agent stops without a claim that held; blocks only while its Harness drive runs',
         write: { path, content: `${JSON.stringify(merged, null, 2)}\n`, expect: [STOP_HOOK_COMMAND] },
     };
 }
+/**
+ * The Claude Code `SessionStart` hook with matcher `compact`: right after a compaction it prints
+ * `reticle context --compact` — what this session proved, what failed, what is still owed — back
+ * into the agent's fresh context. Reticle holds the memory; this is how it is handed back without
+ * the agent having to remember to ask.
+ *
+ * Written by default wherever the CLAUDE.md rule is (it only reads the project's own `.reticle/`, and
+ * prints nothing where there is none). Removable like any hook: delete the entry.
+ */
+export const COMPACT_HOOK_COMMAND = `npx ${RETICLE_NPM_PACKAGE} context --compact`;
+const COMPACT_TITLE = 'Claude Code resume-after-compaction hook';
+const SESSION_START_EVENT = 'SessionStart';
+const COMPACT_MATCHER = 'compact';
+export function compactHookStep(path, existing) {
+    const settings = null === existing || undefined === existing ? {} : parseSettings(existing);
+    if (settings === undefined) {
+        return {
+            title: COMPACT_TITLE,
+            target: path,
+            status: StepStatus.MANUAL,
+            detail: `${CLAUDE_SETTINGS_PATH} is not a JSON object, so it was left alone. Add a SessionStart hook (matcher "${COMPACT_MATCHER}") running \`${COMPACT_HOOK_COMMAND}\``,
+        };
+    }
+    const hooks = isObject(settings['hooks']) ? settings['hooks'] : {};
+    const start = Array.isArray(hooks[SESSION_START_EVENT])
+        ? hooks[SESSION_START_EVENT]
+        : [];
+    if (JSON.stringify(start).includes(COMPACT_HOOK_COMMAND)) {
+        return {
+            title: COMPACT_TITLE,
+            target: path,
+            status: StepStatus.ALREADY,
+            detail: 'hook already installed',
+        };
+    }
+    const entry = {
+        matcher: COMPACT_MATCHER,
+        hooks: [{ type: 'command', command: COMPACT_HOOK_COMMAND }],
+    };
+    const merged = { ...settings, hooks: { ...hooks, [SESSION_START_EVENT]: [...start, entry] } };
+    return {
+        title: COMPACT_TITLE,
+        target: path,
+        status: StepStatus.APPLY,
+        detail: 'after a context compaction, hand the agent back what this session proved and still owes',
+        write: {
+            path,
+            content: `${JSON.stringify(merged, null, 2)}\n`,
+            expect: [COMPACT_HOOK_COMMAND],
+        },
+    };
+}
+/**
+ * Every hook this run writes into `.claude/settings.json`, each merged on top of the one before, so
+ * two steps writing the same file cannot undo each other.
+ */
+export function claudeSettingsSteps(path, existing, options) {
+    const steps = [];
+    let current = existing;
+    if (options.stop) {
+        const stop = stopHookStep(path, current);
+        steps.push(stop);
+        current = stop.write?.content ?? current;
+    }
+    if (options.compact) {
+        const compact = compactHookStep(path, current);
+        steps.push(compact);
+        current = compact.write?.content ?? current;
+    }
+    const claude = PROMPT_HOOK_AGENTS.find((agent) => PromptHookAgent.CLAUDE_CODE === agent.id);
+    if (true === options.prompt && claude !== undefined) {
+        steps.push(promptHookStep({
+            spec: claude,
+            path,
+            existing: current ?? null,
+            ...(options.bin === undefined ? {} : { bin: options.bin }),
+        }));
+    }
+    return steps;
+}
+/**
+ * The prompt-capture hook, for each agent found. On by default, because the request is what a
+ * verdict is checked against and an agent forgets to relay it. `--no-prompt-capture` skips it;
+ * `"promptCapture": false` in `.reticle.json` keeps every agent hook from writing; `reticle hook uninstall`
+ * removes exactly what this added.
+ */
+const PROMPT_TITLE = 'Prompt capture';
+const NOTICE_TARGET = '.reticle/request.json';
+/**
+ * The consent line. Names all that the agent hooks keep, what leaves with a linked run and under
+ * which setting, and the one switch that stops all of it.
+ */
+export const PROMPT_CAPTURE_NOTICE = 'Reticle keeps these in .reticle/ in this project, with secrets removed: each prompt you send, the tool calls your agent makes (commands, file edits, web calls), its model, and its closing message for each turn. ' +
+    'Tool calls stay on this machine. ' +
+    'When the project is linked (reticle connect, or RETICLE_API_KEY in the environment), each synced run sends the model to your own workspace. ' +
+    'Your prompts and the closing messages also go there with the runs, and to the Harness, unless "shareRequests": false is in .reticle.json. ' +
+    'Stop all of it: "promptCapture": false in .reticle.json, or RETICLE_PROMPT_CAPTURE=0 on this machine.';
+export function promptHookStep(target) {
+    const { spec, path, existing, bin } = target;
+    const title = `${PROMPT_TITLE}: ${spec.label}`;
+    const merged = installPromptHook(spec, existing, bin);
+    const then = spec.activation === undefined ? '' : `. ${spec.activation}`;
+    if (PromptHookStatus.ALREADY === merged.status) {
+        return {
+            title,
+            target: path,
+            status: StepStatus.ALREADY,
+            detail: `hook already installed${then}`,
+        };
+    }
+    if (PromptHookStatus.MANUAL === merged.status) {
+        return {
+            title,
+            target: path,
+            status: StepStatus.MANUAL,
+            detail: `${path} is not plain JSON, so it was left alone. Add a prompt-submit hook that runs \`${promptHookCommand(spec.id)}\` (${spec.docs})`,
+        };
+    }
+    return {
+        title,
+        target: path,
+        status: StepStatus.APPLY,
+        detail: `save each prompt, tool call, model and closing message to .reticle/; never blocks the agent${then}`,
+        write: { path, content: merged.content, expect: [promptHookCommand(spec.id)] },
+    };
+}
+/** The steps for every detected agent, then the one consent line when any hook is in place. */
+export function promptHookSteps(targets, claude, bin) {
+    const steps = targets.map((target) => promptHookStep(bin === undefined ? target : { ...target, bin }));
+    if (0 === steps.length && !claude) {
+        return steps;
+    }
+    return [
+        ...steps,
+        {
+            title: PROMPT_TITLE,
+            target: NOTICE_TARGET,
+            status: StepStatus.NOTICE,
+            detail: PROMPT_CAPTURE_NOTICE,
+        },
+    ];
+}

package/dist/project/agent-rules.d.ts

@@ -90,7 +90,7 @@ export declare const DEV_SERVER_POLICY = "**A dev server already running when `r
  * NOT to, how, and the guards against calling something proven when it is not. Everything an agent
  * needs only at the moment it hits a specific situation lives in RETICLE.md, named at the end.
  */
-export declare const RULE_BODY = "## Verifying with Reticle\n\nThis app is instrumented by **Reticle**, an in-app verification layer exposed as `reticle_*` MCP tools and the `npx @reticlehq/server` CLI (always through npx: Reticle's server is not installed into this project). Verifying is part of \"done\", not an optional extra.\n\n**Verify when you have changed something a user can see or do.** A component, a form, a route, a request, a piece of state that reaches the screen. Do it BEFORE telling the user it is complete. Reading the diff proves nothing and unit tests do not run the app.\n\n**Do not reach for Reticle when the change cannot show up in the running app.** It costs tool calls and the user's patience, and a verdict over an unrelated flow proves nothing about what you changed. Skip it for: documentation, comments, tests, build config, CI, dependency bumps with no user-facing effect, backend or CLI work with no UI surface, and any change to a project that is not a running web app. Say in one line that you skipped verification and why, rather than silently not doing it.\n\n**How to verify:**\n\n- Drive the flow with `reticle_act_and_wait({ ref, action, until })`. It names the consequence you expect BEFORE the action, which is the difference between a check and a rationalisation.\n- Batch a multi-step journey (a login, a form) into one `reticle_act { steps: [...] }` rather than one round trip per field.\n- Read the surrounding evidence with `reticle_look { action: \"page\" | \"state\" }` and `reticle_observe { action: \"network\" | \"console\" }`.\n- **Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** `reticle_act` and everything else move or read the app and prove nothing, so a session ending without one of those two has no result however many tools it used.\n- Covered flows: `npx @reticlehq/server gate` reports which recorded flows the changed files affect and whether they still pass.\n\n**Setting Reticle up? You are mid-sequence \u2014 do not stop until a verdict exists.** The whole of it\nis: instrument the app \u2192 get a dev server running \u2192 open the app in a browser \u2192 drive one flow \u2192\nreport the verdict. Every step is yours to do, and none of them needs the user. Stopping short leaves an app that\nlooks installed and can verify nothing, which is the commonest way this goes wrong. `/reticle`\ncarries the recovery ladder; never report the install as finished without a verdict to point at.\n\n**Nothing connected? Get the app running.**\n\n**A dev server already running when `reticle init` ran does not have Reticle in its bundle.** It read the build config at boot; `init` edited it afterwards. It serves the old bundle and no session appears. In order:\n\n1. **A dev server was already running?** Restart it, then hard-reload the tab. \"Something is listening\" does not mean the right bundle is served.\n2. **Nothing was running?** Start it in the BACKGROUND and say so in one line. `reticle_session { action: \"list\" }` gives you this project's own dev command in `next_action`; use that, never compose one. Started after `init`, it needs no restart.\n\nStopping to ask is how a verification turn ends with nothing verified.\n\nFour guards, none optional:\n\n1. **Never run two at once.** One dev server on the app's port. Restarting a stale one means stopping it first, not starting a second alongside it.\n2. **Never guess the command.** It comes from `package.json` scripts. No recognisable dev script means say so and stop, not invent one.\n3. **Never kill anything you did not start**, and never a daemon or a port holder. The one exception is the restart above, and say in one line that you did it.\n4. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer.\n\nA dev server that is already running does not pick up an edited build config or a newly created plugin file \u2014 restart it and hard-reload the tab. And if a server IS listening and still nothing connects, the cause is the SDK not loading in the page, not a missing dev server; do not tell the user to start one they are already running.\n\n**Finish `src/reticle-dev.ts` before you claim setup is done.** `init` writes it and cannot always fill it in: a store that needs an argument only reading the code supplies (Jotai atoms, an XState actor, a TanStack `queryClient`) is left as a commented `registerStore` line. A file that registers nothing looks exactly like a finished one, and `reticle_look { action: \"state\" }` then returns empty forever \u2014 which is indistinguishable from an app that has nothing to report, so it reads as success. Uncomment the line, complete it, and prove it by driving one flow and seeing your keys come back. If `init` told you to restart your client, this is the job waiting for you on the other side of that restart.\n\n**Verify each feature as you finish it, not all of them at the end.** Asked for four, build one, drive it, get a verdict, then start the second. A red verdict after four builds has four suspects; after one it has none.\n\n**Capture what a change is FOR while you are building it, not afterwards.** The business outcome a change is meant to produce is known only while the change is being made. Pass `intent` when a flow is saved, so the saved flow carries the reason it exists. A flow without one replays for months and then reports \"step 3 failed\" instead of what stopped being true for a user.\n\n**Honesty, which is the whole point:**\n\n- **`verified: \"unknown\"` is not a pass.** It means Reticle drove the app and could not tell what happened; `verifiedReason` says which clause decided that. Report it as unknown, never as working.\n- **`verified: \"no-fault\"` is not a pass either.** It means nothing was DECLARED to prove: the page settled and no channel complained, but you asserted nothing, so there is no verification. You get it whenever `until` is omitted. Name a consequence the action changes \u2014 a signal, a request, a route, or store state \u2014 and call again.\n- **Never weaken a check to make it green.** Downgrading, skipping or deleting an assertion is a finding, not a fix.\n- **If Reticle cannot run** (no daemon, or this is not a running web app), say so. Do not skip verification silently.\n- **Setup is not finished until one real flow has been driven and produced a verdict.** `init` exiting 0, the tools appearing, and a session being listed are all things that happen before anything has been verified.\n\n**The `/reticle` skill runs this whole loop for you** \u2014 detect, connect, drive one flow, report. If your client does not have it, install it once: `/plugin marketplace add reticlehq/reticle` then `/plugin install reticle@reticlehq` in Claude Code, or `npx skills add reticlehq/reticle` anywhere the skills CLI works.\n\n**A tool you need is missing?** Call `reticle_tools` before assuming it: this surface merges several families behind an `action`, so what looks absent is usually one argument away. It is the verify loop and nothing else on purpose, and a daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises the wider set \u2014 it reads that at startup, so it takes effect on the next one.\n\n**Report Reticle's own defects with `reticle_session { action: \"feedback\" }` the moment you notice**, then carry on with your task. You are the user Reticle is built for and the only one who can say what it cost you, and that knowledge is gone when your context is.\n\n\uD83D\uDCC4 **The rest is in [RETICLE.md](./RETICLE.md): what to do when the tools are missing, when a result carries `version_skew` or `update_available`, when `reticle_look { action: \"state\" }` comes back empty, and how to write a feedback report that can be acted on. Read it when you hit one of those, not before.**";
+export declare const RULE_BODY = "## Verifying with Reticle\n\nThis app is instrumented by **Reticle**, an in-app verification layer exposed as `reticle_*` MCP tools and the `npx @reticlehq/server` CLI (always through npx: Reticle's server is not installed into this project). Verifying is part of \"done\", not an optional extra.\n\n**Verify when you have changed something a user can see or do.** A component, a form, a route, a request, a piece of state that reaches the screen. Do it BEFORE telling the user it is complete. Reading the diff proves nothing and unit tests do not run the app.\n\n**Do not reach for Reticle when the change cannot show up in the running app.** It costs tool calls and the user's patience, and a verdict over an unrelated flow proves nothing about what you changed. Skip it for: documentation, comments, tests, build config, CI, dependency bumps with no user-facing effect, backend or CLI work with no UI surface, and any change to a project that is not a running web app. Say in one line that you skipped verification and why, rather than silently not doing it.\n\n**How to verify \u2014 the rules to keep in mind on every call:**\n\n1. **Only `verified: \"yes\"` is a pass.** `\"no-fault\"` (nothing was declared \u2014 you omitted `until`) and `\"unknown\"` (Reticle could not tell; `verifiedReason` says why) are not a pass: report them as not proved, never as working.\n2. **Name the consequence BEFORE acting:** `reticle_act_and_wait({ target, action, until })` (add `durable: true` if it must survive a reload). Only it, `reticle_assert` and `reticle_act { steps }` produce a verdict; everything else proves nothing.\n3. **A journey is one call:** `reticle_act { steps: [{ target, action, expect }] }` runs every step and stops at the first `expect` that fails. The last step's `expect` is the end state you were asked to deliver.\n4. **Text checks are exact-case.** Add `ignoreCase: true` only when case truly does not matter.\n5. **Target by `{ testid }` or `{ role, name }`.** An ambiguous target is refused, never guessed.\n6. **On a failure, read `expected` / `observed` / the nearest candidates before retrying.** Never weaken a check to make it green.\n7. **Open `screenshot.path` only when the look matters;** `reticle_observe { since }` has the rest.\n8. **Predicates:** `{ kind: \"signal\", name }` \u00B7 `{ kind: \"net\", method, urlContains, status }` \u00B7 `{ kind: \"route\", pathname }` \u00B7 `{ kind: \"state\", path, equals }` \u00B7 `{ kind: \"element\", query: { role, name } }` \u00B7 `{ kind: \"text\", contains }` \u00B7 `allOf` / `anyOf` / `not`.\n9. **No session?** `reticle_session { action: \"list\" }` and do its `next_action`. **No app connected at all?** Ask the user, then run `npx @reticlehq/server init` in the app's own folder. **A version-skew warning?** `npx @reticlehq/server stop`, then retry.\n10. **End with the Reticle result block the server gives you**, verbatim.\n11. **If your context was compacted or you lost track, run `npx @reticlehq/server context --compact` first.** It is the daemon's own record of what was proved, what failed and what is still owed.\n\nCovered flows: `npx @reticlehq/server gate` reports which recorded flows the changed files affect and whether they still pass.\n\n**Setting Reticle up? You are mid-sequence \u2014 do not stop until a verdict exists.** The whole of it\nis: instrument the app \u2192 get a dev server running \u2192 open the app in a browser \u2192 drive one flow \u2192\nreport the verdict. Every step is yours to do, and none of them needs the user. Stopping short leaves an app that\nlooks installed and can verify nothing, which is the commonest way this goes wrong. `/reticle`\ncarries the recovery ladder; never report the install as finished without a verdict to point at.\n\n**Nothing connected? Get the app running.**\n\n**A dev server already running when `reticle init` ran does not have Reticle in its bundle.** It read the build config at boot; `init` edited it afterwards. It serves the old bundle and no session appears. In order:\n\n1. **A dev server was already running?** Restart it, then hard-reload the tab. \"Something is listening\" does not mean the right bundle is served.\n2. **Nothing was running?** Start it in the BACKGROUND and say so in one line. `reticle_session { action: \"list\" }` gives you this project's own dev command in `next_action`; use that, never compose one. Started after `init`, it needs no restart.\n\nStopping to ask is how a verification turn ends with nothing verified.\n\nFour guards, none optional:\n\n1. **Never run two at once.** One dev server on the app's port. Restarting a stale one means stopping it first, not starting a second alongside it.\n2. **Never guess the command.** It comes from `package.json` scripts. No recognisable dev script means say so and stop, not invent one.\n3. **Never kill anything you did not start**, and never a daemon or a port holder. The one exception is the restart above, and say in one line that you did it.\n4. **The permission prompt belongs to your host.** Never bypass, suppress or auto-approve it, and take a refusal as the answer.\n\nIf a server IS listening and still nothing connects, the cause is the SDK not loading in the page, not a missing dev server; do not tell the user to start one they are already running.\n\n**Finish `src/reticle-dev.ts` before you claim setup is done.** `init` writes it and cannot always fill it in: a store that needs an argument only reading the code supplies (Jotai atoms, an XState actor, a TanStack `queryClient`) is left as a commented `registerStore` line. A file that registers nothing looks exactly like a finished one, and `reticle_look { action: \"state\" }` then returns empty forever \u2014 which is indistinguishable from an app that has nothing to report, so it reads as success. Uncomment the line, complete it, and prove it by driving one flow and seeing your keys come back. If `init` told you to restart your client, this is the job waiting for you on the other side of that restart.\n\n**Verify each feature as you finish it, not all of them at the end.** Asked for four, build one, drive it, get a verdict, then start the second. A red verdict after four builds has four suspects; after one it has none.\n\n**Capture what a change is FOR while you are building it, not afterwards.** The business outcome a change is meant to produce is known only while the change is being made. Pass `intent` when a flow is saved, so the saved flow carries the reason it exists. A flow without one replays for months and then reports \"step 3 failed\" instead of what stopped being true for a user.\n\n**Honesty, which is the whole point:**\n\n- **If Reticle cannot run** (no daemon, or this is not a running web app), say so. Do not skip verification silently.\n- **Setup is not finished until one real flow has been driven and produced a verdict.** `init` exiting 0, the tools appearing, and a session being listed are all things that happen before anything has been verified.\n\n**The `/reticle` skill runs this whole loop for you** \u2014 detect, connect, drive one flow, report. If your client does not have it, install it once: `/plugin marketplace add reticlehq/reticle` then `/plugin install reticle@reticlehq` in Claude Code, or `npx skills add reticlehq/reticle --skill reticle` anywhere the skills CLI works.\n\n**A tool you need is missing?** Call `reticle_tools` before assuming it: this surface merges several families behind an `action`, so what looks absent is usually one argument away. It is the verify loop and nothing else on purpose: every other tool is one `reticle_run` call away. Do not restart the daemon with `RETICLE_ADVERTISE_ALL_TOOLS=1`: it uses older tool names that the rules above do not.\n\n**Report Reticle's own defects with `reticle_session { action: \"feedback\" }` the moment you notice**, then carry on with your task. You are the user Reticle is built for and the only one who can say what it cost you, and that knowledge is gone when your context is.\n\n\uD83D\uDCC4 **The rest is in [RETICLE.md](./RETICLE.md): what to do when the tools are missing, when a result carries `version_skew` or `update_available`, when `reticle_look { action: \"state\" }` comes back empty, and how to write a feedback report that can be acted on. Read it when you hit one of those, not before.**";
 /** The full-rules file, written verbatim (no markers: `init` owns this file entirely). */
 export declare function reticleMdFile(): string;
 export declare const AgentRuleStatus: {

package/dist/project/agent-rules.js

@@ -19,7 +19,7 @@
  */
 import { NPX } from '../register/mcp.js';
 import { RETICLE_NPM_PACKAGE } from '../version.js';
-import { DISCOVERY_CALL_URL, DISCOVERY_EMAIL_COMMAND } from '@reticlehq/core';
+import { AgentRules, DISCOVERY_CALL_URL, DISCOVERY_EMAIL_COMMAND, FEEDBACK_KIND_CHOICES, } from '@reticlehq/core';
 /** Project-root instruction files the agent re-reads every session. */
 export const CLAUDE_MD_PATH = 'CLAUDE.md';
 export const AGENTS_MD_PATH = 'AGENTS.md';
@@ -40,7 +40,7 @@ export const RETICLE_MD_PATH = 'RETICLE.md';
 /** Cursor project rule; the frontmatter `alwaysApply` keeps it in context on every turn. */
 export const CURSOR_RULE_PATH = '.cursor/rules/reticle.mdc';
 /** Markers delimiting the managed block so a re-run is idempotent and the block stays updatable. */
-const RULE_BEGIN = '<!-- reticle:begin (managed by `reticle init` — edit outside these markers) -->';
+const RULE_BEGIN = AgentRules.BEGIN;
 const RULE_END = '<!-- reticle:end -->';
 /**
  * Does this file already carry the managed block?
@@ -118,13 +118,21 @@ This app is instrumented by **Reticle**, an in-app verification layer exposed as
 
 **Do not reach for Reticle when the change cannot show up in the running app.** It costs tool calls and the user's patience, and a verdict over an unrelated flow proves nothing about what you changed. Skip it for: documentation, comments, tests, build config, CI, dependency bumps with no user-facing effect, backend or CLI work with no UI surface, and any change to a project that is not a running web app. Say in one line that you skipped verification and why, rather than silently not doing it.
 
-**How to verify:**
+**How to verify — the rules to keep in mind on every call:**
 
-- Drive the flow with \`reticle_act_and_wait({ ref, action, until })\`. It names the consequence you expect BEFORE the action, which is the difference between a check and a rationalisation.
-- Batch a multi-step journey (a login, a form) into one \`reticle_act { steps: [...] }\` rather than one round trip per field.
-- Read the surrounding evidence with \`reticle_look { action: "page" | "state" }\` and \`reticle_observe { action: "network" | "console" }\`.
-- **Only \`reticle_act_and_wait\` and \`reticle_assert\` produce a verdict.** \`reticle_act\` and everything else move or read the app and prove nothing, so a session ending without one of those two has no result however many tools it used.
-- Covered flows: \`${CLI} gate\` reports which recorded flows the changed files affect and whether they still pass.
+1. **Only \`verified: "yes"\` is a pass.** \`"no-fault"\` (nothing was declared — you omitted \`until\`) and \`"unknown"\` (Reticle could not tell; \`verifiedReason\` says why) are not a pass: report them as not proved, never as working.
+2. **Name the consequence BEFORE acting:** \`reticle_act_and_wait({ target, action, until })\` (add \`durable: true\` if it must survive a reload). Only it, \`reticle_assert\` and \`reticle_act { steps }\` produce a verdict; everything else proves nothing.
+3. **A journey is one call:** \`reticle_act { steps: [{ target, action, expect }] }\` runs every step and stops at the first \`expect\` that fails. The last step's \`expect\` is the end state you were asked to deliver.
+4. **Text checks are exact-case.** Add \`ignoreCase: true\` only when case truly does not matter.
+5. **Target by \`{ testid }\` or \`{ role, name }\`.** An ambiguous target is refused, never guessed.
+6. **On a failure, read \`expected\` / \`observed\` / the nearest candidates before retrying.** Never weaken a check to make it green.
+7. **Open \`screenshot.path\` only when the look matters;** \`reticle_observe { since }\` has the rest.
+8. **Predicates:** \`{ kind: "signal", name }\` · \`{ kind: "net", method, urlContains, status }\` · \`{ kind: "route", pathname }\` · \`{ kind: "state", path, equals }\` · \`{ kind: "element", query: { role, name } }\` · \`{ kind: "text", contains }\` · \`allOf\` / \`anyOf\` / \`not\`.
+9. **No session?** \`reticle_session { action: "list" }\` and do its \`next_action\`. **No app connected at all?** Ask the user, then run \`${CLI} init\` in the app's own folder. **A version-skew warning?** \`${CLI} stop\`, then retry.
+10. **End with the Reticle result block the server gives you**, verbatim.
+11. **If your context was compacted or you lost track, run \`${CLI} context --compact\` first.** It is the daemon's own record of what was proved, what failed and what is still owed.
+
+Covered flows: \`${CLI} gate\` reports which recorded flows the changed files affect and whether they still pass.
 
 **Setting Reticle up? You are mid-sequence — do not stop until a verdict exists.** The whole of it
 is: instrument the app → get a dev server running → open the app in a browser → drive one flow →
@@ -136,7 +144,7 @@ carries the recovery ladder; never report the install as finished without a verd
 
 ${DEV_SERVER_POLICY}
 
-A dev server that is already running does not pick up an edited build config or a newly created plugin file — restart it and hard-reload the tab. And if a server IS listening and still nothing connects, the cause is the SDK not loading in the page, not a missing dev server; do not tell the user to start one they are already running.
+If a server IS listening and still nothing connects, the cause is the SDK not loading in the page, not a missing dev server; do not tell the user to start one they are already running.
 
 **Finish \`src/reticle-dev.ts\` before you claim setup is done.** \`init\` writes it and cannot always fill it in: a store that needs an argument only reading the code supplies (Jotai atoms, an XState actor, a TanStack \`queryClient\`) is left as a commented \`registerStore\` line. A file that registers nothing looks exactly like a finished one, and \`reticle_look { action: "state" }\` then returns empty forever — which is indistinguishable from an app that has nothing to report, so it reads as success. Uncomment the line, complete it, and prove it by driving one flow and seeing your keys come back. If \`init\` told you to restart your client, this is the job waiting for you on the other side of that restart.
 
@@ -146,15 +154,12 @@ A dev server that is already running does not pick up an edited build config or
 
 **Honesty, which is the whole point:**
 
-- **\`verified: "unknown"\` is not a pass.** It means Reticle drove the app and could not tell what happened; \`verifiedReason\` says which clause decided that. Report it as unknown, never as working.
-- **\`verified: "no-fault"\` is not a pass either.** It means nothing was DECLARED to prove: the page settled and no channel complained, but you asserted nothing, so there is no verification. You get it whenever \`until\` is omitted. Name a consequence the action changes — a signal, a request, a route, or store state — and call again.
-- **Never weaken a check to make it green.** Downgrading, skipping or deleting an assertion is a finding, not a fix.
 - **If Reticle cannot run** (no daemon, or this is not a running web app), say so. Do not skip verification silently.
 - **Setup is not finished until one real flow has been driven and produced a verdict.** \`init\` exiting 0, the tools appearing, and a session being listed are all things that happen before anything has been verified.
 
-**The \`/reticle\` skill runs this whole loop for you** — detect, connect, drive one flow, report. If your client does not have it, install it once: \`/plugin marketplace add reticlehq/reticle\` then \`/plugin install reticle@reticlehq\` in Claude Code, or \`npx skills add reticlehq/reticle\` anywhere the skills CLI works.
+**The \`/reticle\` skill runs this whole loop for you** — detect, connect, drive one flow, report. If your client does not have it, install it once: \`/plugin marketplace add reticlehq/reticle\` then \`/plugin install reticle@reticlehq\` in Claude Code, or \`npx skills add reticlehq/reticle --skill reticle\` anywhere the skills CLI works.
 
-**A tool you need is missing?** Call \`reticle_tools\` before assuming it: this surface merges several families behind an \`action\`, so what looks absent is usually one argument away. It is the verify loop and nothing else on purpose, and a daemon started with \`RETICLE_ADVERTISE_ALL_TOOLS=1\` advertises the wider set — it reads that at startup, so it takes effect on the next one.
+**A tool you need is missing?** Call \`reticle_tools\` before assuming it: this surface merges several families behind an \`action\`, so what looks absent is usually one argument away. It is the verify loop and nothing else on purpose: every other tool is one \`reticle_run\` call away. Do not restart the daemon with \`RETICLE_ADVERTISE_ALL_TOOLS=1\`: it uses older tool names that the rules above do not.
 
 **Report Reticle's own defects with \`reticle_session { action: "feedback" }\` the moment you notice**, then carry on with your task. You are the user Reticle is built for and the only one who can say what it cost you, and that knowledge is gone when your context is.
 
@@ -175,7 +180,7 @@ The short version lives in your agent instruction file (\`CLAUDE.md\` / \`AGENTS
 
 They have not been loaded yet, which is not the same as broken. \`init\` registers the MCP server, but a client reads its server list at startup and does not re-read it, and no slash command reloads it (\`/mcp\` only manages servers already loaded).
 
-Ask the human to RESTART their client: restart Claude Code, reload the window in Cursor, or hit Start in \`.vscode/mcp.json\` in VS Code. Then wait and carry on. This is once per machine, because Reticle is registered globally and later projects already have the tools. \`${CLI} status\` works meanwhile and says whether the daemon is up and whether the app has connected.
+On Claude Code and Codex, run \`${CLI} init --relaunch\` and run the command it prints: it restarts this conversation with the tools. Elsewhere, ask the human to restart their client: reload the window in Cursor, or press Start in \`.vscode/mcp.json\` in VS Code. Then wait and carry on. This is once per machine, because Reticle is registered globally and later projects already have the tools. \`${CLI} status\` works meanwhile and says whether the daemon is up and whether the app has connected.
 
 ## A result carries \`verify_next\`
 
@@ -202,12 +207,12 @@ Finish that file when you see it. It is what lets you check what the app BELIEVE
 - **Send it with \`reticle_session { action: "feedback" }\` the moment you notice.** One call, then carry straight on. Do not batch reports, do not wait until the task is done, and do not decide something is too minor. The small awkward things are what nobody ever reports, so they never get fixed.
 - **Everything counts, in both directions.** A tool that returned something wrong (\`bug\`), something Reticle could not observe at all (\`gap\`), a verdict you could not act on (\`ambiguity\`), something you wished existed (\`feature_request\`), something that works but costs too many calls (\`improvement\`).
 - **Setup and installation count too, and are the easiest to lose.** Anything that went wrong while installing, wiring, or starting Reticle: a step in the docs that did not match reality, a plugin that had to be added by hand, a daemon that would not start, an OS-specific detour. You hit these before any verification runs, which is exactly why they go unreported.
-- **When the tools are not reachable yet**, file the same report from the shell: \`${CLI} feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"\`. It needs no daemon and no working install, so a Reticle that broke before it started can still be reported.
+- **When the tools are not reachable yet**, file the same report from the shell: \`${CLI} feedback --agent --kind ${FEEDBACK_KIND_CHOICES} "what happened"\`. It needs no daemon and no working install, so a Reticle that broke before it started can still be reported.
 - **Write it so it can be acted on.** For a failure: what you called, what you expected, what you got, and the call trail in \`trace\`. For a request: the GOAL in \`need\` (not your guess at the solution), what improves in \`impact\`, and how you work around it today in \`currentApproach\`. That workaround is usually the most useful line in the report. Set \`model\` to the model you are running.
 - **Working around a Reticle defect in silence is the one thing not to do.** A silent workaround is how the same defect survives to the next user.
 - **Report defects in *Reticle*, not in the app under test.** A bug you find in this app is Reticle working as intended; that one belongs in your report to the user.
 - **Never include app source, secrets, user data, or customer records** in a report.
-- **When the person you work with is stuck, or Reticle got in their way, offer them a call with the founder** (${DISCOVERY_CALL_URL}) or leaving an email with \`${DISCOVERY_EMAIL_COMMAND}\`. That conversation is where Reticle's direction comes from. Offer it; never book a call or submit an email for them.
+- **When the person you work with is stuck, or Reticle got in their way, offer them a call with the founder** (${DISCOVERY_CALL_URL}) or a note with their email: \`${DISCOVERY_EMAIL_COMMAND}\`. That conversation is where Reticle's direction comes from. Offer it; never book a call or submit an email for them.
 
 ## More
 

package/dist/project/refresh-rules.js

@@ -17,9 +17,10 @@
  * install.
  */
 import { join } from 'node:path';
+import { AgentRules } from '@reticlehq/core';
 import { mergeMarkedInstruction, AgentRuleStatus, hasManagedBlock } from './agent-rules.js';
 /** The instruction files the managed block lives in. Cursor's rule file is regenerated whole. */
-export const RULE_FILES = ['CLAUDE.md', 'AGENTS.md'];
+export const RULE_FILES = AgentRules.FILES;
 /**
  * Refresh every instruction file that already carries a Reticle block.
  *

package/dist/register/codex-toml.d.ts

@@ -8,3 +8,15 @@
 export declare function codexServerTokens(existing: string | null, serversKey: string): string[];
 /** Does this config already declare a Reticle server under our name? */
 export declare function codexDeclaresOurServer(existing: string | null, serversKey: string): boolean;
+/**
+ * Does this config NAME a Reticle server at all, in any shape?
+ *
+ * Wider than {@link codexDeclaresOurServer}, which asks whether the entry holds a command we can
+ * read. A `url` entry, one that only has an `env` table, or an inline `mcp_servers = { … }` has no
+ * command and args, so it reads as absent there. `codex mcp add reticle` REPLACES such an entry
+ * without a word and exits 0, so anything that registers through that command has to ask this.
+ *
+ * Structural rather than a substring match: a project called `reticle`, under
+ * `[projects."/home/u/reticle"]`, does not name a server.
+ */
+export declare function codexNamesOurServer(existing: string | null, serversKey: string): boolean;

package/dist/register/codex-toml.js

@@ -142,3 +142,47 @@ export function codexServerTokens(existing, serversKey) {
 export function codexDeclaresOurServer(existing, serversKey) {
     return 0 < codexServerTokens(existing, serversKey).length;
 }
+/**
+ * Our key, as a KEY, inside an inline table's text: `reticle = …`, `"reticle" = …`, or the dotted
+ * `reticle.command = …`. A key follows the `{` or a `,`, and its quotes match, so a value that merely
+ * starts with the name (`command = "reticle.js"`) is not one.
+ */
+const OUR_KEY_INLINE = new RegExp(`(?:^|[{,])\\s*(?:${MCP_SERVER_NAME}|"${MCP_SERVER_NAME}"|'${MCP_SERVER_NAME}')\\s*[.=]`);
+/**
+ * Does this config NAME a Reticle server at all, in any shape?
+ *
+ * Wider than {@link codexDeclaresOurServer}, which asks whether the entry holds a command we can
+ * read. A `url` entry, one that only has an `env` table, or an inline `mcp_servers = { … }` has no
+ * command and args, so it reads as absent there. `codex mcp add reticle` REPLACES such an entry
+ * without a word and exits 0, so anything that registers through that command has to ask this.
+ *
+ * Structural rather than a substring match: a project called `reticle`, under
+ * `[projects."/home/u/reticle"]`, does not name a server.
+ */
+export function codexNamesOurServer(existing, serversKey) {
+    if (null === existing)
+        return false;
+    const want = ourTablePath(serversKey);
+    const isOurs = (path) => want.every((segment, i) => path[i] === segment);
+    let table = [];
+    for (const rawLine of existing.split(/\r?\n/)) {
+        const line = withoutComment(rawLine).trim();
+        const header = /^\[{1,2}([^\]]+)\]{1,2}$/.exec(line);
+        if (null !== header) {
+            table = keyPath(header[1] ?? '');
+            if (isOurs(table))
+                return true;
+            continue;
+        }
+        const assignment = /^([^=]+)=(.*)$/.exec(line);
+        if (null === assignment)
+            continue;
+        const path = [...table, ...keyPath(assignment[1] ?? '')];
+        if (isOurs(path))
+            return true;
+        // `mcp_servers = { reticle = { … } }`: the whole table is one inline value, our key inside it.
+        if (samePath(path, [serversKey]) && OUR_KEY_INLINE.test(assignment[2] ?? ''))
+            return true;
+    }
+    return false;
+}

package/dist/register/mcp.d.ts

@@ -58,14 +58,14 @@ export declare function npxServerArgs(): string[];
  * @param tokens every string in the entry's command + args, in any of the client shapes.
  */
 export declare function isReticleRegistration(tokens: readonly string[]): boolean;
-interface ClaudeAddCommand {
+interface CliAddCommand {
     command: string;
     args: string[];
     /** Human-readable form of the same command, for reports and manual fallback. */
     display: string;
 }
 /** `claude mcp add reticle -s user -- npx @reticlehq/server mcp` — registers globally for all projects (portless). */
-export declare function claudeAddCommand(): ClaudeAddCommand;
+export declare function claudeAddCommand(): CliAddCommand;
 /**
  * Is a `reticle` server already registered with Claude Code, in any scope this project sees?
  *
@@ -89,6 +89,19 @@ export declare function claudeAvailableProbe(): {
     command: string;
     args: string[];
 };
+/**
+ * `codex mcp add reticle -- npx @reticlehq/server mcp` — Codex keeps the entry in its own
+ * `~/.codex/config.toml`, shared by the desktop app and the CLI, so one registration covers both.
+ *
+ * It REPLACES an existing entry of the same name and still exits 0, so callers run it only when the
+ * config names no `reticle` server at all (see `codexNamesOurServer`).
+ */
+export declare function codexAddCommand(): CliAddCommand;
+/** Probe args for whether the `codex` CLI is installed at all. */
+export declare function codexAvailableProbe(): {
+    command: string;
+    args: string[];
+};
 /**
  * The Windows `cmd /c npx` registration. Printed on every Windows init, not only when the `claude`
  * CLI is missing — a successful `claude mcp add` of bare `npx` is exactly the failure that reported

package/dist/register/mcp.js

@@ -36,6 +36,7 @@ export const NPX = 'npx';
 const RETICLE_PACKAGE = RETICLE_NPM_PACKAGE;
 const MCP_SUBCOMMAND = 'mcp';
 const CLAUDE_CLI = 'claude';
+const CODEX_CLI = 'codex';
 /** Windows `cmd /c` — the spawn that PowerShell's execution policy does not gate. */
 const WINDOWS_SHELL = 'cmd';
 const WINDOWS_SHELL_C = '/c';
@@ -140,6 +141,21 @@ export function claudeHasReticle(io, projectDir, configDir = process.env['CLAUDE
 export function claudeAvailableProbe() {
     return { command: CLAUDE_CLI, args: ['--version'] };
 }
+/**
+ * `codex mcp add reticle -- npx @reticlehq/server mcp` — Codex keeps the entry in its own
+ * `~/.codex/config.toml`, shared by the desktop app and the CLI, so one registration covers both.
+ *
+ * It REPLACES an existing entry of the same name and still exits 0, so callers run it only when the
+ * config names no `reticle` server at all (see `codexNamesOurServer`).
+ */
+export function codexAddCommand() {
+    const args = [MCP_SUBCOMMAND, 'add', MCP_SERVER_NAME, '--', ...serverInvocation()];
+    return { command: CODEX_CLI, args, display: `${CODEX_CLI} ${args.join(' ')}` };
+}
+/** Probe args for whether the `codex` CLI is installed at all. */
+export function codexAvailableProbe() {
+    return { command: CODEX_CLI, args: ['--version'] };
+}
 /**
  * The Windows `cmd /c npx` registration. Printed on every Windows init, not only when the `claude`
  * CLI is missing — a successful `claude mcp add` of bare `npx` is exactly the failure that reported

package/dist/register/prompt-hooks.d.ts

@@ -0,0 +1,123 @@
+export declare const PromptHookAgent: {
+    readonly CLAUDE_CODE: "claude-code";
+    readonly CURSOR: "cursor";
+    readonly CODEX: "codex";
+    readonly GEMINI: "gemini";
+    readonly WINDSURF: "windsurf";
+    /** VS Code agent mode and Copilot CLI: both read `.github/hooks/*.json`. */
+    readonly COPILOT: "copilot";
+    readonly FACTORY: "factory-droid";
+};
+export type PromptHookAgent = (typeof PromptHookAgent)[keyof typeof PromptHookAgent];
+export declare const PromptHookStatus: {
+    readonly APPLY: "apply";
+    readonly ALREADY: "already";
+    readonly MANUAL: "manual";
+};
+export type PromptHookStatus = (typeof PromptHookStatus)[keyof typeof PromptHookStatus];
+/** The words every version of our command holds, and no other command does. */
+export declare const PROMPT_HOOK_MARKER = " hook prompt --agent ";
+export declare const AGENT_FLAG = "--agent";
+/**
+ * The command, PINNED to the version that installed it. Unpinned, `npx` runs whatever version its
+ * cache holds: on a real machine that was 3.4.0, which has no `hook` command, so every prompt was
+ * lost while the hook still exited quietly. A re-run of `init` moves the pin forward.
+ */
+export declare const promptHookCommand: (agent: PromptHookAgent) => string;
+/** The words every version of the post-tool command holds. */
+export declare const TOOL_HOOK_MARKER = " hook tool --agent ";
+/**
+ * The post-tool command: keeps one of the agent's own tool calls in `.reticle/episodes/`. Pinned
+ * for the same reason as the prompt command.
+ */
+export declare const toolHookCommand: (agent: PromptHookAgent) => string;
+/** One place in the config that holds a list of hook entries, and the entry we add to it. */
+interface HookSlot {
+    /** Keys from the top of the file down to the list. */
+    readonly path: readonly string[];
+    readonly entry: (command: string) => Record<string, unknown>;
+    /** The command this slot runs, when it is not the prompt command. */
+    readonly command?: (agent: PromptHookAgent) => string;
+}
+/**
+ * Run the installed CLI with node, and fall back to the pinned npx command when that file is gone.
+ * npx's own start (~350 ms on a laptop) came before every prompt and tool call. The path is this
+ * machine's; the npx half is what every other machine runs, so the entry stays correct for a
+ * teammate. `node` exits at once on a missing file, before it reads stdin, so the fallback still
+ * gets the payload.
+ */
+export declare function directHookCommand(bin: string, npx: string): string;
+export interface PromptHookSpec {
+    readonly id: PromptHookAgent;
+    readonly label: string;
+    /** Project-relative configs this agent reads, first wins. We write to the first that exists. */
+    readonly paths: readonly string[];
+    /** Written when none of `paths` exists. */
+    readonly defaultPath: string;
+    /** Keys we add at the top of a NEW file, and remove again when the file holds nothing else. */
+    readonly header?: Readonly<Record<string, unknown>>;
+    readonly slots: readonly HookSlot[];
+    /** Project-relative directories that show the agent is used here. */
+    readonly projectMarkers: readonly string[];
+    /** Home-relative directories that show the agent is on this machine. */
+    readonly homeMarkers: readonly string[];
+    readonly docs: string;
+    /** What the user must do before the agent runs a hook it was given, when writing it is not enough. */
+    readonly activation?: string;
+}
+export declare const PROMPT_HOOK_AGENTS: readonly PromptHookSpec[];
+/**
+ * The agents with no prompt hook that can be written, which therefore rely on the MCP instructions
+ * telling the agent to declare the request. Each one was checked on 2026-10-14: no prompt-submit
+ * event, or one whose config format the vendor does not document well enough to write.
+ */
+export declare const MCP_FALLBACK_AGENTS: readonly string[];
+/** One agent found here: its spec, its config's absolute path, and what that file holds now. */
+export interface PromptHookTarget {
+    readonly spec: PromptHookSpec;
+    readonly path: string;
+    readonly existing: string | null;
+    /** The installed CLI's bin, when known. See `directHookCommand`. */
+    readonly bin?: string;
+}
+/**
+ * The agents used in `projectDir` or installed under `home`, each with the config to write.
+ *
+ * Only those: a `.gemini/settings.json` in the repository of somebody who has never run Gemini is
+ * litter, and it makes the next tool's detection wrong too. `claudeCli` counts Claude Code as
+ * present, because it keeps its registration behind its CLI rather than in a folder.
+ *
+ * `home` undefined reads the project only. `reticle hook install` passes that: it adds the hook to
+ * a project already set up, and an agent installed on this machine is not one the PROJECT uses.
+ * Reading the home folder there wrote five committed configs into a repository that had `.claude/`.
+ */
+export declare function promptHookTargets(io: {
+    exists(path: string): boolean;
+    readFile(path: string): string | null;
+}, projectDir: string, home: string | undefined, claudeCli: boolean, join: (...parts: string[]) => string): PromptHookTarget[];
+/** The project-relative config to write, given which files exist. */
+export declare function promptHookPath(spec: PromptHookSpec, exists: (path: string) => boolean): string;
+/** THIS version's entry is in every slot. An older version's entry is replaced by install. */
+export declare function promptHookInstalled(spec: PromptHookSpec, text: string | null): boolean;
+/**
+ * THIS version is installed, but some slot runs it through npx alone (~426 ms of npx start per
+ * call): an install from before the direct form. Any machine's bin counts as direct, so a
+ * teammate's path is never rewritten with this one's.
+ */
+export declare function promptHookNpxOnly(spec: PromptHookSpec, text: string | null): boolean;
+/** Our entry merged into the config. `content` is the text to write; MANUAL keeps the text as it is. */
+export declare function installPromptHook(spec: PromptHookSpec, text: string | null, 
+/** The installed CLI's bin, when known: the hook runs it directly. See `directHookCommand`. */
+bin?: string): {
+    status: PromptHookStatus;
+    content: string;
+};
+/**
+ * The config with our entries removed. `content` null means delete the file: it holds nothing but
+ * what install added. A config that is not ours to parse is never changed.
+ */
+export declare function uninstallPromptHook(spec: PromptHookSpec, text: string | null): {
+    changed: boolean;
+    content: string | null;
+};
+export {};