@reticlehq/init 3.6.0 → 3.8.0

package/dist/plan/plan.js

@@ -3,53 +3,28 @@
  * contents, produce an ordered list of steps — each marked apply / manual / already / skip. The
  * runner performs the `write` side-effects; this module decides *what* should happen.
  */
-import { Framework, UiLibrary, installCommand, installCommandParts } from '../detect/detect.js';
-import { installFailureHint } from '../diagnose/install-hint.js';
-import { installRetries } from '../diagnose/install-retries.js';
-import { claudeAddCommand, claudeProjectMcpJson, mcpManual } from '../register/mcp.js';
+import { claudeAddCommand, claudeProjectMcpJson, codexAddCommand, mcpManual, } from '../register/mcp.js';
+import { codexNamesOurServer } from '../register/codex-toml.js';
 import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, CLAUDE_PROJECT_CONFIG, CLAUDE_PROJECT_SPEC, McpClient, } from '../register/mcp-clients.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH, SLASH_COMMAND_BODY, SLASH_COMMAND_SIGNATURE, } from '../register/slash-command.js';
 import { mergeMarkedInstruction, reticleMdFile, cursorRuleFile, AgentRuleStatus, CLAUDE_MD_PATH, markedBlock, AGENTS_MD_PATH, RETICLE_MD_PATH, CURSOR_RULE_PATH, } from '../project/agent-rules.js';
 import { cspStep } from '../diagnose/csp-step.js';
+import { HTML_INDEX_PATH } from '../patch/static-page.js';
 import { frameworkSteps } from './framework-adapter.js';
-import { FRAMEWORK_ADAPTERS, RETICLE_BROWSER_SDK, RETICLE_REACT_KIT } from './framework-adapter.js';
+import { installStep } from './framework-adapter.js';
 import { MCP_TARGET, StepStatus } from './plan-types.js';
 export { DEPS_TARGET, MCP_TARGET, StepStatus, } from './plan-types.js';
 import { join } from 'node:path';
-import { reticleConfigContent, usesReactKit } from '../patch/snippets.js';
+import { reticleConfigContent } from '../patch/snippets.js';
 import { configWithInstallSource } from '../project/install-source-config.js';
 import { portMoveDetail, retargetConfigPort } from './port-steps.js';
 import { containerisedStep, uiLibraryStep, webGlCanvasStep, windowsMcpNoteStep, } from './notices.js';
 import { existingConfigProblem, projectIdOf, RETICLE_CONFIG_FILE, } from '../detect/existing-config.js';
-import { CLAUDE_SETTINGS_PATH, stopHookStep } from './stop-hook-step.js';
+import { CLAUDE_SETTINGS_PATH, claudeSettingsSteps, promptHookSteps } from './stop-hook-step.js';
+import { PRETTIERIGNORE_PATH, RETICLE_IGNORE_ENTRY, ignoresReticle, withReticleIgnored, } from '../patch/prettier-ignore.js';
 // Re-exported: it moved to the module that reads it, and every existing importer says `plan.js`.
 export { RETICLE_CONFIG_FILE };
-/**
- * Pin the SDK to the CLI's own version.
- *
- * `pnpm add -D @reticlehq/react` once installed an older release in one project while npm and yarn
- * took the current one in the next — a stale registry metadata cache, invisible to everyone. A
- * version-skewed SDK talking to a newer daemon is the `-32000` failure path: the app connects, the
- * protocol disagrees, and nothing on either side names a version. Asking for the CLI's exact version
- * makes the cache irrelevant, and a skewed pair impossible to install by accident.
- */
-function pinnedPackages(packages, version) {
-    if (version === undefined || 0 === version.length)
-        return packages;
-    return packages.map((p) => `${p}@${version}`);
-}
-/**
- * The dev-dependencies `reticle init` installs — kit (or sensor) first, build plugin next.
- *
- * `uiLibrary` matters because the framework does not always name the renderer. The rule below was
- * already written for Nuxt, correctly, and applied only there: a Vue app on plain Vite is
- * `Framework.VITE` and a SvelteKit app renders Svelte, and both were being handed the React kit
- * right after `init` had detected the real UI library and said so on screen.
- */
-export function frameworkPackages(framework, uiLibrary = UiLibrary.UNKNOWN) {
-    const kit = usesReactKit(uiLibrary, framework) ? RETICLE_REACT_KIT : RETICLE_BROWSER_SDK;
-    return FRAMEWORK_ADAPTERS[framework].packages(kit);
-}
+export { frameworkPackages } from './framework-adapter.js';
 /**
  * Where the agent-facing files go, which is not always where the app is.
  *
@@ -65,8 +40,9 @@ function agentFile(input, relPath) {
 }
 const CLAUDE_MCP_TITLE = 'MCP server (Claude, global)';
 function claudeMcpStep(input) {
-    if (!input.claudeCli)
+    if (!input.claudeCli) {
         return null;
+    }
     if (input.mcpExists) {
         return {
             title: CLAUDE_MCP_TITLE,
@@ -92,7 +68,36 @@ function claudeMcpStep(input) {
  * parse is reported with a paste-able block rather than overwritten, and everything else is written.
  */
 function otherClientSteps(input) {
-    return (input.detectedClients ?? []).map((detected) => clientStep(clientSpec(detected.id), detected.configPath, detected.existing));
+    return (input.detectedClients ?? []).map((detected) => {
+        const spec = clientSpec(detected.id);
+        return (codexCliStep(spec, detected.configPath, detected.existing, input) ??
+            clientStep(spec, detected.configPath, detected.existing));
+    });
+}
+/**
+ * Codex, registered through its own CLI instead of a printed block (#1238).
+ *
+ * `mergeClientConfig` answers MANUAL for TOML, since we never edit it blind. `codex mcp add` does
+ * the editing, so with the binary on PATH nothing is left for a human. It REPLACES an entry of the
+ * same name and exits 0, so this answers only when the config names no `reticle` server at all, in
+ * any shape. An entry somebody wrote — a local build, a `url` — falls through to `clientStep`, which
+ * leaves it alone (ALREADY) or hands over the block (MANUAL), exactly as before.
+ */
+function codexCliStep(spec, configPath, existing, input) {
+    if (McpClient.CODEX !== spec.id || true !== input.codexCli) {
+        return null;
+    }
+    if (codexNamesOurServer(existing, spec.serversKey)) {
+        return null;
+    }
+    const cmd = codexAddCommand();
+    return {
+        title: `MCP server (${spec.label})`,
+        target: configPath,
+        status: StepStatus.APPLY,
+        detail: `register reticle with ${spec.label} (${cmd.display})`,
+        exec: { command: cmd.command, args: cmd.args, fallback: cmd.display },
+    };
 }
 /** One client's step: already-correct is left alone, an unparseable file gets a paste-able block. */
 function clientStep(spec, configPath, existing) {
@@ -131,8 +136,9 @@ function clientStep(spec, configPath, existing) {
  * they get the notice instead.
  */
 function claudeProjectStep(input) {
-    if (input.claudeCli || true !== input.insideClaudeCode)
+    if (input.claudeCli || true !== input.insideClaudeCode) {
         return null;
+    }
     const path = agentFile(input, CLAUDE_PROJECT_CONFIG);
     return clientStep(CLAUDE_PROJECT_SPEC, path, input.claudeProjectConfig ?? null);
 }
@@ -198,8 +204,9 @@ function mcpSteps(input) {
         });
     }
     const windowsNote = windowsMcpNoteStep(input);
-    if (windowsNote !== null)
+    if (windowsNote !== null) {
         steps.push(windowsNote);
+    }
     return steps;
 }
 const SLASH_COMMAND_TITLE = 'The /reticle command';
@@ -211,8 +218,9 @@ const SLASH_COMMAND_TITLE = 'The /reticle command';
  * our signature is left exactly as it is.
  */
 function commandIsSettled(content) {
-    if (null === content || content === undefined)
+    if (null === content || content === undefined) {
         return false;
+    }
     return content === SLASH_COMMAND_BODY || !content.includes(SLASH_COMMAND_SIGNATURE);
 }
 /**
@@ -224,8 +232,9 @@ function commandIsSettled(content) {
  * whole file is Reticle's, so a stale one is rewritten.
  */
 function commandStepFor(path, present, content) {
-    if (!present)
+    if (!present) {
         return null;
+    }
     return commandIsSettled(content)
         ? {
             title: SLASH_COMMAND_TITLE,
@@ -268,18 +277,34 @@ const AGENT_RULE_DETAIL = 'teach the agent to verify features with Reticle after
  */
 function ruleWriteDetail(existing, file) {
     const hasContent = existing !== null && existing !== undefined && existing.trim().length > 0;
-    if (!hasContent)
+    if (!hasContent) {
         return `${AGENT_RULE_DETAIL} — creates ${file}`;
+    }
     const added = markedBlock().split('\n').length - 1;
     return (`${AGENT_RULE_DETAIL} — APPENDS ${String(added)} lines to your existing ${file}, ` +
         'inside `reticle:begin`/`reticle:end` markers; delete the marked block to undo');
 }
 const RETICLE_MD_TITLE = 'Full agent rules';
 const RETICLE_MD_DETAIL = 'the reference the always-loaded rule points at (when NOT to verify, recovery, feedback)';
+/**
+ * A line that is only an import of AGENTS.md (`@AGENTS.md`, `@./AGENTS.md`). Claude Code reads the
+ * imported file as part of CLAUDE.md, so the rule `agentsMdStep` writes there already reaches it, and
+ * a second copy in CLAUDE.md would load the rule twice on every turn (#1680).
+ */
+const IMPORTS_AGENTS_MD = /^[ \t]*@(?:\.\/)?AGENTS\.md[ \t]*\r?$/m;
 function claudeRuleStep(input) {
-    if (!input.claudeCli)
+    if (!input.claudeCli) {
         return null;
+    }
     const path = agentFile(input, CLAUDE_MD_PATH);
+    if (IMPORTS_AGENTS_MD.test(input.claudeMdContent ?? '')) {
+        return {
+            title: AGENT_RULE_TITLE,
+            target: path,
+            status: StepStatus.ALREADY,
+            detail: `CLAUDE.md imports ${AGENTS_MD_PATH}, so the Reticle rule written there reaches Claude Code through the import; no second copy`,
+        };
+    }
     const r = mergeMarkedInstruction(input.claudeMdContent);
     if (r.status === AgentRuleStatus.ALREADY) {
         return {
@@ -305,10 +330,12 @@ function claudeRuleStep(input) {
  */
 function cursorRuleStep(input) {
     const cursorGlobal = (input.detectedClients ?? []).some((c) => c.id === McpClient.CURSOR);
-    if (!cursorGlobal && true !== input.cursorProjectPresent)
+    if (!cursorGlobal && true !== input.cursorProjectPresent) {
         return null;
-    if (input.cursorProjectPresent !== true && input.claudeCli)
+    }
+    if (input.cursorProjectPresent !== true && input.claudeCli) {
         return null;
+    }
     // The whole file is Reticle's — init created it — so a stale one is REWRITTEN rather than merged.
     // Comparing content is what makes the rule updatable; comparing existence made it permanent.
     const path = agentFile(input, CURSOR_RULE_PATH);
@@ -429,85 +456,44 @@ function reticleMdStep(input) {
  * noise.
  */
 function agentRuleSteps(input) {
-    if (!input.options.mcp)
+    if (!input.options.mcp) {
         return [];
+    }
     return [...stepsForAgents(input, (a) => a.ruleStep), agentsMdStep(input), reticleMdStep(input)];
 }
 /**
- * What to say when the install command fails.
+ * Keep `.reticle/` out of the project's `prettier --check`.
  *
- * pnpm's `minimumReleaseAge` refuses any release younger than the configured window — a deliberate
- * supply-chain policy, not a bug — with `ERR_PNPM_NO_MATURE_MATCHING_VERSION`. Unpinned it silently
- * resolves to an OLDER version instead, which is how an app ends up running a stale SDK against a
- * newer daemon: the connection succeeds, the protocol disagrees, and the failure surfaces as -32000
- * with nothing naming a version. Pinning turns that into this loud failure, which is the better
- * trade — but only if the message says what to do about it.
- */
-/**
- * Is this package already declared at the version we would pin?
- *
- * The caret is the point. `npm i -D pkg@3.2.0` WRITES `^3.2.0`, so on every later run the pinned
- * `3.2.0` failed a string comparison against the range npm had just created, and init re-installed
- * for ever. Only the two forms a package manager writes by itself are read - an exact version, and
- * `^`/`~` over that same version.
+ * When the project uses Prettier, `init` adds `.reticle/` to the project's `.prettierignore`.
+ * The nested `.reticle/.gitignore` does not help — Prettier only reads the ignore file of the
+ * directory it runs from — and matching Prettier's exact JSON output is a losing game, so
+ * excluding the directory is the root-cause fix (#1560).
  *
- * Everything else installs. A false "already" leaves somebody with no SDK and an install that
- * claims to have run; a redundant install only costs time, so the unreadable cases go the safe way.
+ * SKIP when the project does not use Prettier. ALREADY when `.reticle/` is already excluded.
+ * Otherwise APPLY: create the file, or append the entry to the existing one.
  */
-function alreadyDeclared(declared, pinned) {
-    if (declared === undefined)
-        return false;
-    if (pinned === undefined || 0 === pinned.length)
-        return true;
-    return declared === pinned || `^${pinned}` === declared || `~${pinned}` === declared;
-}
-function installStep(input) {
-    const pm = input.detection.packageManager;
-    // `Detection.packageManagerCommand` (see `preflight.ts`, #1149). Falling back to `pm` covers every
-    // caller that never went through preflight (tests, and any future one).
-    const pmCommand = input.detection.packageManagerCommand ?? pm;
-    const packages = pinnedPackages(frameworkPackages(input.detection.framework, input.detection.uiLibrary), input.options.sdkVersion);
-    const command = installCommand(pm, packages, pmCommand);
-    /*
-     * A re-run over an already-wired project does NO dependency work.
-     *
-     * Reported from the field: `init` on an instrumented npm-workspaces project ran a pnpm dependency
-     * migration, which moved the existing `node_modules` aside and broke the dev server. Whatever
-     * manager gets chosen, the redundant install is the step that touches the tree — so the fix that
-     * matters is not running one that nothing needs. `init` is documented as idempotent; this is the
-     * step that was not.
-     */
-    const declared = input.detection.dependencies ?? {};
-    const version = input.options.sdkVersion;
-    const names = frameworkPackages(input.detection.framework, input.detection.uiLibrary);
-    if (names.length > 0 && names.every((n) => alreadyDeclared(declared[n], version))) {
-        return {
-            title: 'Install dependencies',
-            target: 'package.json',
-            status: StepStatus.ALREADY,
-            detail: `${names.join(', ')} already declared${version === undefined || 0 === version.length ? '' : ` at ${version}`}`,
-        };
+function prettierIgnoreStep(input) {
+    if (true !== input.detection.usesPrettier) {
+        return null;
     }
-    if (!input.options.install) {
+    const existing = input.prettierIgnoreSource ?? null;
+    if (null !== existing && ignoresReticle(existing)) {
         return {
-            title: 'Install dependencies',
-            target: 'package.json',
-            status: StepStatus.MANUAL,
-            detail: command,
+            title: 'Prettier ignore',
+            target: PRETTIERIGNORE_PATH,
+            status: StepStatus.ALREADY,
+            detail: '.reticle/ already excluded from Prettier',
         };
     }
-    const parts = installCommandParts(pm, packages, [], pmCommand);
+    const content = withReticleIgnored(existing);
     return {
-        title: 'Install dependencies',
-        target: 'package.json',
+        title: 'Prettier ignore',
+        target: PRETTIERIGNORE_PATH,
         status: StepStatus.APPLY,
-        detail: command,
-        exec: {
-            command: parts.command,
-            args: parts.args,
-            fallback: `${command}\n\n${installFailureHint(pm, pmCommand)}`,
-        },
-        retries: installRetries(pm, packages, frameworkPackages(input.detection.framework, input.detection.uiLibrary), input.options.sdkVersion, pmCommand),
+        detail: null === existing
+            ? 'create .prettierignore excluding .reticle/ so `prettier --check` passes'
+            : 'add .reticle/ to .prettierignore so `prettier --check` passes',
+        write: { path: PRETTIERIGNORE_PATH, content, expect: [RETICLE_IGNORE_ENTRY] },
     };
 }
 const RETICLE_CONFIG_TITLE = 'Reticle config';
@@ -526,12 +512,15 @@ const AGENT_ROOT_CONFIG_TITLE = 'Reticle config (agent root)';
  * and the two files are byte-identical, so neither can disagree with the other about the port or the
  * project identity.
  */
-function agentRootConfigStep(input, content) {
+function agentRootConfigStep(input, content, renamedFrom) {
     const root = input.agentFileRoot;
-    if (root === undefined || 0 === root.length)
+    if (root === undefined || 0 === root.length) {
         return [];
+    }
     const path = agentFile(input, RETICLE_CONFIG_FILE);
-    const existingProject = projectIdOf(input.agentRootConfigSource);
+    const declared = projectIdOf(input.agentRootConfigSource);
+    // The root's copy of the id `--new-id` just replaced is this checkout's, not another app's.
+    const existingProject = declared === renamedFrom ? undefined : declared;
     const wantedProject = projectIdOf(content);
     /**
      * A monorepo has more than one app and the root can only point at one of them.
@@ -561,6 +550,19 @@ function agentRootConfigStep(input, content) {
             },
         ];
     }
+    // Several apps: a root config names one and is wrong for the rest. Not written; an agent at the
+    // root is served whichever app's daemon is live, and one started in an app reads that app's.
+    if (true === input.agentRootSeveralApps && existingProject === undefined) {
+        return [
+            {
+                title: AGENT_ROOT_CONFIG_TITLE,
+                target: path,
+                status: StepStatus.NOTICE,
+                detail: 'not written: this workspace has several apps and the root can name only one. Run the ' +
+                    "agent from an app's directory to pin it to that app.",
+            },
+        ];
+    }
     if (input.agentRootConfigSource === content) {
         return [
             {
@@ -582,7 +584,7 @@ function agentRootConfigStep(input, content) {
         },
     ];
 }
-function reticleConfigStep(input, content, onDisk, movedFrom) {
+function reticleConfigStep(input, content, onDisk, movedFrom, renamedFrom) {
     if (true === input.reticleConfigExists) {
         const problem = existingConfigProblem(onDisk);
         if (problem !== undefined) {
@@ -598,15 +600,17 @@ function reticleConfigStep(input, content, onDisk, movedFrom) {
         // The one thing a re-run can still learn: which channel the user actually arrived through.
         // See configWithInstallSource — it only ever ADDS a field that is absent.
         const backfilled = configWithInstallSource(onDisk, input.installSource);
-        if (backfilled !== undefined || movedFrom !== undefined) {
+        if (backfilled !== undefined || movedFrom !== undefined || renamedFrom !== undefined) {
             const port = input.options.port;
             return {
                 title: RETICLE_CONFIG_TITLE,
                 target: RETICLE_CONFIG_FILE,
                 status: StepStatus.APPLY,
-                detail: movedFrom !== undefined && port !== undefined
-                    ? portMoveDetail(movedFrom, port)
-                    : 'record which install route this project came through',
+                detail: renamedFrom !== undefined
+                    ? `this checkout's own project id: ${String(input.options.projectId)} (was ${renamedFrom}, the id it was copied with)`
+                    : movedFrom !== undefined && port !== undefined
+                        ? portMoveDetail(movedFrom, port)
+                        : 'record which install route this project came through',
                 write: { path: RETICLE_CONFIG_FILE, content: backfilled ?? onDisk ?? content },
             };
         }
@@ -634,11 +638,27 @@ function reticleConfigStep(input, content, onDisk, movedFrom) {
  * requested port, and a config still naming the old one is half of a split brain (see
  * port-steps.ts). Only the port moves; the identity stays the one already on disk.
  */
+/**
+ * `--new-id`: the config with `projectId` replaced by the one derived for THIS checkout, or null when
+ * there is nothing to replace. A copied repository keeps the original's `.reticle.json`, and init
+ * otherwise keeps a config on disk as it is, so nothing else gives the copy an id of its own.
+ */
+function withOwnProjectId(source, options) {
+    const id = options.projectId;
+    const from = projectIdOf(source);
+    if (true !== options.newId || id === undefined || from === undefined || from === id) {
+        return null;
+    }
+    const fields = JSON.parse(source);
+    return { code: `${JSON.stringify({ ...fields, projectId: id }, null, 2)}\n`, from };
+}
 function reticleConfigSteps(input) {
     const existing = input.reticleConfigSource;
-    const onDisk = true === input.reticleConfigExists && null !== existing && existing !== undefined
+    const copied = true === input.reticleConfigExists && null !== existing && existing !== undefined
         ? existing
         : undefined;
+    const renamed = copied === undefined ? null : withOwnProjectId(copied, input.options);
+    const onDisk = renamed?.code ?? copied;
     const moved = onDisk === undefined ? null : retargetConfigPort(onDisk, input.options.port);
     const content = moved?.code ??
         onDisk ??
@@ -647,29 +667,64 @@ function reticleConfigSteps(input) {
         // config written before this field existed, and the two mean different things.
         input.installSource);
     return [
-        reticleConfigStep(input, content, moved?.code ?? existing, moved?.from),
-        ...agentRootConfigStep(input, content),
+        reticleConfigStep(input, content, moved?.code ?? onDisk, moved?.from, renamed?.from),
+        ...agentRootConfigStep(input, content, renamed?.from),
+        ...(null === renamed ? [] : copiedIdSteps(input, renamed.from)),
     ];
 }
+/**
+ * `--new-id`: the old id where the app quotes it by hand, as in `connect({ projectId: '…' })`. Left
+ * there, the copy's evidence goes on into the original checkout. Only the whole quoted literal moves:
+ * the id is a hash-suffixed name nothing else spells.
+ */
+function copiedIdSteps(input, from) {
+    const id = input.options.projectId;
+    if (id === undefined) {
+        return [];
+    }
+    return (input.copiedIdSources ?? []).map(({ path, source }) => ({
+        title: RETICLE_CONFIG_TITLE,
+        target: path,
+        status: StepStatus.APPLY,
+        detail: `the project id the app names by hand: ${id} (was ${from})`,
+        write: {
+            path,
+            content: ['"', "'", '`'].reduce((code, q) => code.replaceAll(`${q}${from}${q}`, `${q}${id}${q}`), source),
+            expect: [id],
+        },
+    }));
+}
 export function buildPlan(input) {
+    const cspSteps = cspStep(input);
+    const prettierIgnore = prettierIgnoreStep(input);
     const steps = [
-        ...cspStep(input),
+        ...cspSteps,
         ...mcpSteps(input),
         ...agentRuleSteps(input),
         ...slashCommandSteps(input),
-        ...(true === input.hooks
-            ? [stopHookStep(agentFile(input, CLAUDE_SETTINGS_PATH), input.claudeSettingsContent)]
-            : []),
+        ...claudeSettingsSteps(agentFile(input, CLAUDE_SETTINGS_PATH), input.claudeSettingsContent, {
+            stop: true === input.hooks,
+            // Beside the CLAUDE.md rule: the same agent, the same consent to write its instruction files.
+            compact: input.options.mcp && input.claudeCli,
+            prompt: true === input.claudePromptHook,
+            bin: input.hookBin,
+        }),
+        ...promptHookSteps(input.promptHooks ?? [], true === input.claudePromptHook, input.hookBin),
         ...uiLibraryStep(input),
         ...webGlCanvasStep(input),
         installStep(input),
         ...reticleConfigSteps(input),
+        ...(prettierIgnore !== null ? [prettierIgnore] : []),
     ];
-    steps.push(...frameworkSteps(input));
+    // Both steps can patch index.html: the connect write must keep the CSP edit that runs first.
+    const patchedIndex = cspSteps.find((step) => step.write?.path === HTML_INDEX_PATH)?.write
+        ?.content;
+    steps.push(...frameworkSteps(patchedIndex === undefined ? input : { ...input, htmlIndexSource: patchedIndex }));
     // LAST, and a notice rather than an action: it is a statement about this machine's shape, and it
     // only matters once every file above has been written. See containerised-dev-server.ts.
     const container = containerisedStep(input);
-    if (container !== null)
+    if (container !== null) {
         steps.push(container);
+    }
     return { framework: input.detection.framework, uiLibrary: input.detection.uiLibrary, steps };
 }

package/dist/plan/stop-hook-step.d.ts

@@ -1,4 +1,34 @@
 import { type Step } from './plan-types.js';
+import { type PromptHookTarget } from '../register/prompt-hooks.js';
 export declare const CLAUDE_SETTINGS_PATH = ".claude/settings.json";
 export declare const STOP_HOOK_COMMAND = "npx @reticlehq/server report --hook";
 export declare function stopHookStep(path: string, existing: string | null | undefined): Step;
+/**
+ * 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 declare const COMPACT_HOOK_COMMAND = "npx @reticlehq/server context --compact";
+export declare function compactHookStep(path: string, existing: string | null | undefined): Step;
+/**
+ * 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 declare function claudeSettingsSteps(path: string, existing: string | null | undefined, options: {
+    stop: boolean;
+    compact: boolean;
+    prompt?: boolean;
+    bin?: string | undefined;
+}): Step[];
+/**
+ * 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 declare const PROMPT_CAPTURE_NOTICE: string;
+export declare function promptHookStep(target: PromptHookTarget): Step;
+/** The steps for every detected agent, then the one consent line when any hook is in place. */
+export declare function promptHookSteps(targets: readonly PromptHookTarget[], claude: boolean, bin?: string): Step[];