@reticlehq/init 3.7.0 → 3.8.0

package/dist/plan/plan-types.d.ts

@@ -8,6 +8,7 @@
 import type { Detection, Framework, UiLibrary } from '../detect/detect.js';
 import type { FoundStore } from '../detect/capabilities.js';
 import type { McpClient } from '../register/mcp-clients.js';
+import type { PromptHookTarget } from '../register/prompt-hooks.js';
 /** Exported so the init telemetry can tell an MCP-registration failure from a dependency install. */
 export declare const MCP_TARGET = "global (claude user scope)";
 /** The step that runs the package manager — the other thing that commonly fails on a user's machine. */
@@ -115,6 +116,11 @@ export interface PlanInput {
      * handing it an io would let any later step reach the disk from inside `buildPlan`.
      */
     cspSources?: Readonly<Record<string, string | undefined>> | undefined;
+    /**
+     * The project's `.prettierignore` content, pre-read so the prettier-ignore step stays pure.
+     * Null when the file does not exist — `init` creates it only when the project uses Prettier.
+     */
+    prettierIgnoreSource?: string | null | undefined;
     /** Whether the `claude` CLI is installed (so we can register the MCP server globally). */
     claudeCli: boolean;
     /** Whether an `reticle` MCP server is already registered with Claude (any scope) — idempotency. */
@@ -217,6 +223,11 @@ export interface PlanInput {
      * when there is no top-level layout and no single group renders `/` (#1538).
      */
     nextLayoutCandidates?: readonly string[] | undefined;
+    /**
+     * The other route-group root layouts when one was chosen to mount into, that do not mount
+     * `<ReticleDev />` themselves: the routes under them render without it.
+     */
+    nextUnmountedLayouts?: readonly string[] | undefined;
     /** Where the dev-only connect component goes — never inside `pages/`, which routes on presence. */
     nextReticleDevPath?: string | undefined;
     /** What the mount file should import — a sibling for App Router, `../components/…` for Pages. */
@@ -325,6 +336,14 @@ export interface PlanInput {
      * see reticleConfigStep for the port that survived every re-run because of it.
      */
     reticleConfigSource?: string | null | undefined;
+    /**
+     * `--new-id`: the app's source files that quote the id being replaced. A hand-written
+     * `connect({ projectId: '…' })` still naming it sends this checkout's evidence to the original.
+     */
+    copiedIdSources?: readonly {
+        path: string;
+        source: string;
+    }[] | undefined;
     /** Current project-root CLAUDE.md content (for the idempotent agent-rule merge), or null/undefined. */
     claudeMdContent?: string | null | undefined;
     /** Current project-root AGENTS.md content (the cross-agent rule), or null/undefined. */
@@ -347,6 +366,12 @@ export interface PlanInput {
     hooks?: boolean | undefined;
     /** Current .claude/settings.json content, or null when absent (the hook is MERGED into it). */
     claudeSettingsContent?: string | null | undefined;
+    /** Install the prompt-capture hook into `.claude/settings.json`: Claude Code is used here. */
+    claudePromptHook?: boolean | undefined;
+    /** Every OTHER agent found here with a prompt hook, and its config as it is now. */
+    promptHooks?: readonly PromptHookTarget[] | undefined;
+    /** See `InitHost.hookBin`. */
+    hookBin?: string | undefined;
     /**
      * Absolute directory the AGENT runs in, when that is not the app's directory.
      *
@@ -369,6 +394,8 @@ export interface PlanInput {
         install: boolean;
         /** Stable project identity derived at init (package.json name + root). Baked into snippets/.reticle.json. */
         projectId?: string;
+        /** `--new-id`: the config on disk takes `projectId` above in place of the id it was copied with. */
+        newId?: boolean;
         /** The CLI's own version, pinned onto the SDK install so a stale registry cache cannot skew it. */
         sdkVersion?: string;
     };

package/dist/plan/plan.d.ts

@@ -3,18 +3,9 @@
  * 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 } from '../detect/detect.js';
 import { type Plan, type PlanInput } from './plan-types.js';
 export { DEPS_TARGET, MCP_TARGET, StepStatus, type Step, type Plan, type PlanInput, } from './plan-types.js';
 import { RETICLE_CONFIG_FILE } from '../detect/existing-config.js';
 export { RETICLE_CONFIG_FILE };
-/**
- * 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 declare function frameworkPackages(framework: Framework, uiLibrary?: UiLibrary): readonly string[];
+export { frameworkPackages } from './framework-adapter.js';
 export declare function buildPlan(input: PlanInput): Plan;

package/dist/plan/plan.js

@@ -3,9 +3,6 @@
  * 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, 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';
@@ -14,44 +11,20 @@ import { mergeMarkedInstruction, reticleMdFile, cursorRuleFile, AgentRuleStatus,
 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, claudeSettingsSteps } 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.
  *
@@ -67,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,
@@ -110,10 +84,12 @@ function otherClientSteps(input) {
  * 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)
+    if (McpClient.CODEX !== spec.id || true !== input.codexCli) {
         return null;
-    if (codexNamesOurServer(existing, spec.serversKey))
+    }
+    if (codexNamesOurServer(existing, spec.serversKey)) {
         return null;
+    }
     const cmd = codexAddCommand();
     return {
         title: `MCP server (${spec.label})`,
@@ -160,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);
 }
@@ -227,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';
@@ -240,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);
 }
 /**
@@ -253,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,
@@ -297,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 {
@@ -334,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);
@@ -458,95 +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.
- *
- * 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?
+ * Keep `.reticle/` out of the project's `prettier --check`.
  *
- * 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}`}`,
-        };
-    }
-    // Never install into a linked tree: the package manager replaces the link (a workspace's tree).
-    if (true === input.nodeModulesLinked) {
-        return {
-            title: 'Install dependencies',
-            target: 'package.json',
-            status: StepStatus.SKIP,
-            detail: `skipped: node_modules is a link to another tree, which an install here would replace; install them where it points: ${command}`,
-        };
+function prettierIgnoreStep(input) {
+    if (true !== input.detection.usesPrettier) {
+        return null;
     }
-    // The person said `--no-install`: a choice, not a step left undone, so not a ⚠.
-    if (!input.options.install) {
+    const existing = input.prettierIgnoreSource ?? null;
+    if (null !== existing && ignoresReticle(existing)) {
         return {
-            title: 'Install dependencies',
-            target: 'package.json',
-            status: StepStatus.SKIP,
-            detail: `skipped (--no-install); install them yourself: ${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';
@@ -565,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.
@@ -634,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) {
@@ -650,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 },
             };
         }
@@ -686,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 ??
@@ -699,12 +667,36 @@ 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 = [
         ...cspSteps,
         ...mcpSteps(input),
@@ -714,11 +706,15 @@ export function buildPlan(input) {
             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] : []),
     ];
     // 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
@@ -727,7 +723,8 @@ export function buildPlan(input) {
     // 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,5 @@
 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;
@@ -20,4 +21,14 @@ export declare function compactHookStep(path: string, existing: string | null |
 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[];

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';
@@ -48,7 +50,7 @@ export function stopHookStep(path, existing) {
         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] },
     };
 }
@@ -116,7 +118,81 @@ export function claudeSettingsSteps(path, existing, options) {
         steps.push(stop);
         current = stop.write?.content ?? current;
     }
-    if (options.compact)
-        steps.push(compactHookStep(path, 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,
+        },
+    ];
+}