@jawache/flow 0.2.1 → 0.3.0

package/dist/types/adapter/domain.d.ts

@@ -1,5 +1,5 @@
-import { type BreadcrumbMoment, type EntrySpec, type GuardrailMoment, type LoadResult, type Moment, type Refusal, type SessionFacts, type TurnAction } from "../language/domain.ts";
-import { type Block, type Bound, type Cause, type Metrics, type MomentsView, type Row, type TerrainNode } from "../engine/domain.ts";
+import { type BreadcrumbMoment, type Ctx, type EntrySpec, type LoadedEntry, type ExecResult, type GuardrailMoment, type LoadResult, type Moment, type Refusal, type SessionFacts, type ShellCommand, type ShellStep, type TurnAction } from "../language/domain.ts";
+import { type AgentOf, type Block, type Bound, type Cause, type Metrics, type MomentsView, type Row, type TerrainNode } from "../engine/domain.ts";
 /**
  * One hook payload, as Claude Code writes it on stdin.
  *
@@ -10,7 +10,13 @@ import { type Block, type Bound, type Cause, type Metrics, type MomentsView, typ
  */
 export interface HookPayload {
     readonly session_id?: string;
+    /** Present on every call a SUBAGENT makes, and only then: the host's id for that one spawn. */
     readonly agent_id?: string;
+    /**
+     * The agent type the host started this subagent as, sent beside `agent_id` on its every call.
+     * Host-written: the session cannot change the message, which is why a category may key on it.
+     */
+    readonly agent_type?: string;
     readonly hook_event_name?: string;
     readonly transcript_path?: string;
     readonly stop_hook_active?: boolean;
@@ -53,54 +59,25 @@ export declare const CONFIG_FILE = "flow.config.ts";
  * Every relative module the config names, READ OUT OF ITS TEXT.
  *
  * A regex over source, deliberately, and it is the only reader that can work here: this is asked
- * about a file that will not import, so anything that had to resolve, parse or evaluate it would
+ * about a file that may not import, so anything that had to resolve, parse or evaluate it would
  * be asking the broken thing to answer for itself. A line like `import { house } from
  * "./guards/house.ts";` survives almost every way a config breaks, because what breaks a config is
  * a missing `.message(…)` or a stray brace two hundred lines below its imports.
  *
  * Only `./…` and `../…` count. A bare specifier is a package — `@jawache/flow`, or a pack somebody
- * published — and a package is not this repo's source to repair. A `..` segment climbs out of the
- * root, so those are dropped too: the config sits at the repo root and the surface is
- * repo-relative or it is nothing. A leading dot in a FOLDER name is ordinary and is kept —
- * `./.guard/house.ts` is a pack like any other.
+ * published — and a package is not this repo's source. A `..` segment climbs out of the root, so
+ * those are dropped too: the config sits at the repo root and `guardPaths` is repo-relative or it
+ * is nothing. A leading dot in a FOLDER name is ordinary and is kept — `./.guard/house.ts` is a pack
+ * like any other.
  *
  * A `from '…'` phrase inside a QUOTED STRING is harvested as well — a rule whose `.message(…)`
- * spells an import line puts that path on the surface though no import named it. ACCEPTED, not
+ * spells an import line puts that path among the guard's files though no import named it. ACCEPTED, not
  * overlooked: telling a real import from a sentence quoting one takes a parser, and a parser is
  * the one thing a file that will not parse cannot give. The cost is bounded and one-directional —
- * the surface only ever WIDENS, it widens only while the config is already refusing every other
- * write, and the commit gate goes on refusing until the config loads green.
+ * the list only ever WIDENS, so the worst it does is report one extra path as a guard file.
  */
 export declare function configImports(configText: string): readonly string[];
-/**
- * THE CONFIG SURFACE — the files a write may target while the guard is broken, and nothing else.
- *
- * Fail-loud says a config that will not load refuses every gated moment, and it is right: a guard
- * that quietly carries on with yesterday's rules is a guard that lies about being there. But taken
- * without exception it also refuses the ONE write that can end the outage, and then the doctrine's
- * own instruction — "adjust the change so it passes, then retry" — is impossible to obey. A human
- * in an editor never meets this (no hooks sit in front of them, so they just undo); an agent that
- * broke the config is locked out of repairing it, and the repo stays broken until a human arrives.
- * Measured twice on the crossing that introduced it, once for real.
- *
- * So the exception is exactly as wide as the repair and no wider: a write whose target is the
- * config or a pack it imports. Everything else still refuses — every other path, every command,
- * and the commit gate, which goes on refusing until the config loads green, so nothing written
- * under the exception can reach a commit unreviewed by a working guard.
- *
- * DERIVED FROM THE CONFIG'S OWN TEXT, and it used to be a two-line constant: the config file, plus
- * one repo's pack folder spelled into the engine. Every other repo got a repair exception over a
- * folder it does not have, and an agent that broke the config there could not reach the pack it
- * broke. The text is readable when the module is not, so nothing is given up by asking it — and the
- * answer now follows whatever a repo actually called the folder.
- *
- * The FOLDER of each imported pack comes with the file, which is the one deliberate widening. A
- * repair is rarely one file: a pack imports its own helpers, and those the config never names. The
- * import graph cannot be walked (walking it means resolving, and resolving is what is broken), so
- * the folder is the honest approximation — and it is exactly the width the old constant had.
- */
-export declare function configSurface(configText: string | null): readonly string[];
-export declare const HOOK_EVENTS: readonly ["session-start", "pre-tool-use", "post-tool-use", "post-tool-use-failure", "stop", "notification"];
+export declare const HOOK_EVENTS: readonly ["session-start", "pre-tool-use", "post-tool-use", "post-tool-use-failure", "stop", "subagent-stop", "notification"];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 export declare function isHookEvent(word: string): word is HookEvent;
 /**
@@ -109,38 +86,48 @@ export declare function isHookEvent(word: string): word is HookEvent;
  *
  * Two facts are stated here rather than discovered by somebody whose rule never fires:
  *
- *   · `commit` is delivered, but not by the harness — git's pre-commit hook calls `flow commit`,
- *     which is why every harness gets the gates for free and why it is in this list at all.
- *   · turn-end BRIEFING is not delivered. Stop's decision object carries no context channel, so a
- *     `breadcrumb().at(turnEnd)` has nowhere to be shown; the guardrail rail at that moment works
- *     perfectly. Reporting an entry that goes dark is `flow status`'s job (F6).
+ *   · `commit` is delivered, but not by the harness — git's pre-commit hook calls `flow hook
+ *     commit`, which is why every harness gets the gates for free and why it is in this list at all.
+ *   · turn-end BRIEFING is delivered, on the `Stop` and `SubagentStop` answers'
+ *     `additionalContext`: the host labels it hook feedback rather than an error, and the agent
+ *     takes one more turn to read it. A refusal at the same hand-back carries the note beside it
+ *     (`toResult`), so the agent is held and told at once rather than held, then told on the next.
  *   · command BRIEFING is delivered, on the same PreToolUse answer the command guardrails use: when
  *     nothing blocks, the hook's `additionalContext` carries the note, and when something does, the
  *     refusal wins — which is the right order, since a blocked command is not about to run. The
  *     files a Bash command reads ride that same answer as touches (`bashReads`), so an area's note
  *     arrives before the output does.
  *
- * It is two lists rather than one because "turn-end" is a word in both vocabularies and the answer
- * differs between them — a single flat list could only lie about one of them.
+ * It is two lists rather than one because a moment is delivered for a KIND of entry: `command` and
+ * `turn-end` are words in both vocabularies, and another harness may carry one rail there and not
+ * the other — a single flat list could only lie about one of them.
  */
 export declare const DELIVERS: {
     guard: readonly GuardrailMoment[];
     brief: readonly BreadcrumbMoment[];
 };
+/**
+ * Does a note at this moment ride a refusal, rather than wait for the call that runs?
+ *
+ * Before a call, a refusal means the call never runs, so a note about it is held back until the
+ * retry that does — and is not marked shown, or it would stay silent until drift. A held turn is
+ * different: the agent is about to act on the refusal anyway, and the note is about that same
+ * turn, so both go to it together.
+ */
+export declare function ridesRefusal(moment: BreadcrumbMoment): boolean;
 /**
  * One event in the engine's vocabulary, minus the two things the engine's own event types demand
- * and this file cannot know: who the session is (`wearing`, which needs the sidecar and the stored
+ * and this file cannot know: who the session is (`wearing`, which needs the transcript and the stored
  * verdict) and how far it has drifted (`tokens`, which needs the transcript). The shell adds both,
  * because both come off disk.
  */
 export type AdapterEvent = {
     readonly rail: "guard";
     readonly moment: GuardrailMoment;
-    readonly file?: {
-        readonly path: string;
-        readonly content: string;
-    } | undefined;
+    readonly file?: Ctx["file"];
     readonly command?: string | undefined;
+    /** command: the line's parse, made once here and handed to the engine with the line. */
+    readonly commands?: Ctx["commands"];
     readonly staged?: readonly string[] | undefined;
     readonly turn?: readonly TurnAction[] | undefined;
     /**
@@ -167,8 +154,14 @@ export interface EventWorld {
     readonly root: string;
     /** A file as it stands right now, or null when it is not there — an Edit is a diff against it. */
     readonly read: (path: string) => string | null;
-    /** What the actor did this turn. Only `stop` asks, so only `stop` pays for it. */
+    /** What the actor did this turn. Only the two turn-end rails ask, so only they pay for it. */
     readonly turn?: (() => readonly TurnAction[]) | undefined;
+    /**
+     * The agent the SESSION itself runs as (`--agent`, or the `agent` setting), or null when it runs
+     * as none. Only `subagent-stop` asks, and only of a payload that names an agent type, because it
+     * costs the parent's transcript: it is how an internal agent's hand-back is told from a subagent's.
+     */
+    readonly sessionAgent?: (() => string | null) | undefined;
     /** The home directory, for a Bash read through `~`. Absent, such a path is simply not named. */
     readonly home?: string | undefined;
     /**
@@ -210,17 +203,19 @@ export declare function wouldBeFile(tool: string, input: Record<string, unknown>
     content: string;
 } | null;
 /**
- * The paths a Bash line would remove — `rm`, `git rm`, and the SOURCE side of `mv` / `git mv`.
+ * The paths a Bash line would remove — `rm`, `git rm`, and the SOURCE side of `mv` / `git mv` —
+ * read from those commands' arguments in the parse.
  *
  * Deletion has no tool of its own: it is a side effect of a shell command, so the delete moment is
- * assembled here or it does not exist at all. `git mv` was the old engine's blind spot; it is
- * covered, and quoting is respected, so a commit message mentioning `rm` is not a removal.
+ * assembled here or it does not exist at all. The parse decides what is a command, so a commit
+ * message mentioning `rm`, a heredoc body that names a file, or an `echo 'rm a.ts'` is not a
+ * removal, while an `rm` inside a `$( … )` or a `bash -c` string, which runs, is.
  *
- * A line that cannot be tokenised yields NOTHING, deliberately: `null` from the tokeniser means "I
- * cannot tell", and a guard that guesses at a line it could not parse is worse than one that stands
- * aside. The command rail still sees the raw line either way.
+ * A line that does not parse yields NOTHING, deliberately: the parse's `null` means "I cannot tell",
+ * and a guard that guesses at a line it could not parse is worse than one that stands aside. The
+ * command rail still sees the raw line either way.
  */
-export declare function deleteTargets(command: string): string[];
+export declare function deleteTargets(commands: readonly ShellCommand[] | null): string[];
 /** Where a Bash call ran, and the two directories its paths are judged against. */
 export interface BashWhere {
     /** The shell's working directory when the call started. */
@@ -242,10 +237,11 @@ export interface BashReads {
 }
 /**
  * The repo paths a Bash command reads or searches — the `READERS` table, a `<` redirect, a `git`
- * pathspec — followed through `cd`, `VAR=`, `for` loops and `$(…)`. The repo root itself is not an
- * area and is left out. Best-effort, failing open: see the section head.
+ * pathspec — read from the parse's steps, and followed through `cd`, `VAR=`, `for` loops and the
+ * commands a `$(…)` runs. The repo root itself is not an area and is left out. Best-effort, failing
+ * open: see the section head. A line that does not parse names nothing.
  */
-export declare function bashReads(command: string, where: BashWhere): BashReads;
+export declare function bashReads(steps: readonly ShellStep[] | null, where: BashWhere): BashReads;
 /**
  * A payload → every event it carries. ZERO OR MORE, and the plural is not hedging.
  *
@@ -258,6 +254,19 @@ export declare function bashReads(command: string, where: BashWhere): BashReads;
  * An event flow was not asked for answers with an empty list, never with an invented moment.
  */
 export declare function toEvent(hook: HookEvent, payload: HookPayload, world: EventWorld): AdapterEvent[];
+/**
+ * Does this hook have nothing to run for this config — so the shell can answer before it reads a
+ * thing?
+ *
+ * A subagent's hand-back costs the parent's transcript (whose agent the session runs as) and the
+ * subagent's own (its turn), and it comes at every hand-back of every subagent. A config that binds
+ * no entry at turn-end, guardrail or breadcrumb, has nothing either read could feed, so neither is
+ * made. A disabled entry binds nothing.
+ *
+ * A repo that is RECORDING never answers early: the tape is for replaying a session against rules
+ * written later, so it keeps every hand-back whatever is bound today.
+ */
+export declare function nothingBound(hook: HookEvent, entries: readonly LoadedEntry[], recording: boolean): boolean;
 /** What a post-tool-use call was about, repo-relative: a path, or nothing this rail can steer on. */
 export declare function touchedPath(payload: HookPayload, root: string): string | null;
 /**
@@ -291,6 +300,26 @@ export type Delta = {
 export declare function snapshotPathspecs(include: readonly string[]): string[];
 /** Of the ignored paths git listed under those heads, the ones a `snapshotInclude` glob matches. */
 export declare function included(listed: readonly string[], include: readonly string[]): string[];
+/**
+ * Of the paths a call changed, the ones the AGENT changed. The rest are git's — a checkout, a reset
+ * or a fast-forward put them there, from a commit the repo already had, and the commit gate judged
+ * that content when it was committed — so they leave the diff before anything reads them: no rule,
+ * no write-back, no breadcrumb, no shell-write row. CONTENT, never the command line: git run by a
+ * recipe is caught the same way, and the `sed` in `git switch x && sed -i … f` is still judged.
+ *
+ * - A file on disk after the call is git's when it is identical to its copy in HEAD after the call.
+ * - A file the call removed is git's when HEAD held it BEFORE the call and does not hold it after:
+ *   git removed it by moving HEAD. A file no commit holds — an untracked file, an included `.env` —
+ *   is the agent's to answer for when it goes.
+ *
+ * `nameStatus` is the call's own diff, `git diff-tree -r -z --name-status --no-renames`, in git's
+ * order. `differsAfter` and `differsBefore` are every path where HEAD's tree after the call, and
+ * before it, disagree with the tree after the call. `differsAfter` is null when HEAD after the call
+ * is no commit the repo had before it — none yet, or one the call made, whose content no gate is
+ * known to have judged — and then nothing is git's. `differsBefore` is null where there was no HEAD
+ * before; for a path gone from disk, being in it is exactly "HEAD held it before".
+ */
+export declare function authored(nameStatus: string, differsAfter: readonly string[] | null, differsBefore: readonly string[] | null): string[];
 /**
  * Git's answer as paths, one per line — the plainest shape git has, and the only one flow parses.
  *
@@ -299,6 +328,37 @@ export declare function included(listed: readonly string[], include: readonly st
  * a command that never ran, and it is no paths.
  */
 export declare function pathLines(stdout: string | null): string[];
+/**
+ * What a commit changes, in the shape the commit gate judges: the files it will hold, which of
+ * those the last commit does not have, and the files it removes. A rename is a removal of the old
+ * path plus an add of the new one, so it needs no shape of its own.
+ */
+export interface StagedChanges {
+    /** Every path the commit will hold that it changes — the subjects of a file rule. */
+    readonly files: readonly string[];
+    /** The `files` the last commit does not have. Undefined when git could not say. */
+    readonly added: readonly string[] | undefined;
+    /** The paths the last commit has and this one will not. */
+    readonly deleted: readonly string[];
+}
+/** NUL-separated paths, as git prints them under `-z` — no quoting, so a path is a path. */
+export declare function nulPaths(stdout: string): string[];
+/**
+ * The staged changes, read from `git diff --cached --name-status --no-renames -z`.
+ *
+ * ONE question to git, and every staged change comes back with what it is: `A` added, `D` deleted,
+ * anything else changed in place. `--no-renames` splits a rename into the delete and the add it is.
+ */
+export declare function stagedChanges(nameStatus: string): StagedChanges;
+/**
+ * The whole tree as one commit — `flow hook commit --all` — against the last commit's own list.
+ *
+ * `present` is every file git can see that is on disk; `tree` is `git ls-tree -r --name-only -z
+ * HEAD`. It fails in two ways that answer differently. Before the first commit there is no HEAD, so
+ * every file is new and nothing is removed. Any other failure is unknown: `added` stays undefined,
+ * so a check asks the disk and refuses rather than allows.
+ */
+export declare function treeChanges(present: readonly string[], tree: ExecResult, hasHead: () => boolean): StagedChanges;
 /** The key one call's snapshot is filed under — the host's `tool_use_id` — or null when it sent none. */
 export declare function callKey(payload: HookPayload): string | null;
 /**
@@ -431,57 +491,56 @@ export interface Answer {
     readonly undone?: Undone | undefined;
 }
 /**
- * Is this event the WRITE that could fix a config that will not load?
+ * What the agent is told beside the load error, on every answer it rides: what that error means.
  *
- * The one exception to fail-loud, and it is deliberately the narrowest shape that works: a write
- * (or a delete) whose target is the guard's own source. `configSurface` above says why that surface
- * is read out of the config's own text rather than resolved.
- *
- * A COMMAND is never a repair, however plausible it looks. `sed -i` on the config would qualify by
- * intent and there is no way to tell it from `rm -rf` before it runs — a command rail sees a string,
- * not a target — so the command rail stays fully closed in the broken state, and the agent's route
- * back is the edit tools, which name the file they are about to write.
- *
- * It lives HERE rather than in the shell beside its caller because it decides and reads nothing.
- * The coverage gate over this file is what keeps the exception's exact width asserted.
+ * The load error says what broke; this says what flow is doing about it. Without it, a call that
+ * went through reads like a guard that judged it and passed.
  */
-export declare function repairs(event: AdapterEvent, surface: readonly string[]): boolean;
+export declare const FLOW_OFF = "flow is OFF until flow.config.ts loads: every write, delete and command goes through unchecked, and every commit is refused.";
 /**
  * WHAT EVERY RAIL ANSWERS WHILE THE CONFIG WILL NOT LOAD — one decision for both ways it can break.
  *
- * A config has two ways of not loading, and they used to get two different answers. One will not
- * IMPORT — a missing module, a syntax error — which the shell catches as a thrown error. The other
- * imports fine and the GRAMMAR refuses it: a missing `.message(…)`, an override naming an entry the
- * pack does not have, a mandatory parameter nobody supplied. Only the first ever reached the repair
- * exception, because the second was refused a layer deeper inside `guard()` — so the break the
- * README and the guidebook both tell a reader to make was the one break an agent could not repair
- * itself out of. To everyone who meets them the two are the same fact, "the guard is entirely off",
- * and now they are the same answer as well.
- *
- * TURN-END IS TOLD, NOT REFUSED. Holding a turn open on a broken config prevents nothing risky —
- * every write, command and commit is already refused and the commit gate stays shut — while it does
- * stop the agent handing back to the one person who can fix it. So the fault is reported and the
- * turn ends.
+ * A config has two ways of not loading. One will not IMPORT — a missing module, a syntax error —
+ * which the shell catches as a thrown error. The other imports fine and the GRAMMAR refuses it: a
+ * missing `.message(…)`, an override naming an entry the pack does not have, a mandatory parameter
+ * nobody supplied. To everyone who meets them the two are the same fact, "the guard is entirely
+ * off", so they get the same answer.
+ *
+ * NOTHING IS REFUSED HERE (docs/user/explanation/fail-loud.md). A guard that refused every call
+ * would refuse the repair too — the fix for a missing package is `npm ci`, a command — and a write
+ * made now reaches the commit gate anyway, which stays shut until the config loads and then checks
+ * the staged files against every guardrail. The cost is the guardrails on commands, which nothing
+ * later can check; the agent is told on every call that they are off.
+ *
+ * TOLD BEFORE THE CALL, ONCE. The load error rides the answer to a session start and to every
+ * write, delete or command about to run — one notice per answer, however many events the payload
+ * carried. A touch never carries it, on either rail: a Read is not told, and a Bash call is told by
+ * its command, not by the files it reads. So the after-call rail, whose events are observed changes
+ * and touches, stays silent: the agent was told when the call was asked for, and saying it again
+ * with the result is the same sentence twice.
+ *
+ * TURN-END IS TOLD, NOT REFUSED. Holding a turn open on a broken config prevents nothing — the
+ * commit gate stays shut — while it does stop the agent handing back to the one person who can fix
+ * it. So the fault is reported and the turn ends. Not as a note either: a turn-end note keeps the
+ * agent working for one more turn, which is the same hold by a softer name.
  *
  * THE ENGINE HAS ITS OWN PAIR OF `!load.ok` BRANCHES — `guard()` blocks with the fault, `brief()`
  * notices it — and they are NOT this rule written twice. They answer a different question: "there
- * is nothing to run, say so", for the two callers that have no repair to make and no turn to end,
- * namely `replay` and the commit gate. Deleting them was considered at F3.B3 and measured first:
- * `flow replay` over a config the grammar refuses reaches `brief()`'s branch and emits the fault
- * notice, so the branch is live and its deletion would have dropped that notice silently. What IS
- * shared is the shape — `Outage extends Answer`, so the hook rail's answer and every other answer
- * are one type rather than two that happen to match.
+ * is nothing to run, say so", for the two callers that have no call to let through and no turn to
+ * end, namely `replay` and the commit gate. `flow replay` over a config the grammar refuses reaches
+ * `brief()`'s branch and emits the fault notice, so that branch is live. What IS shared is the
+ * shape — `Outage extends Answer`, so the hook rail's answer and every other answer are one type.
  */
 export interface Outage extends Answer {
     /**
-     * The sentence turn-end is TOLD instead of being refused with, or null when no turn ended here.
+     * The sentence turn-end is TOLD with, or null when no turn ended here.
      *
-     * It is not `shown`: the Stop rail has no context channel to inject prose into, which is what
-     * `DELIVERS` already says, so the shell writes this one to stderr and answers 0.
+     * It is not `shown`: a note at turn-end keeps the agent working for one more turn, and this
+     * sentence is for the human the turn hands back to, so the shell writes it to stderr and answers 0.
      */
     readonly told: string | null;
 }
-export declare function whileBroken(events: readonly AdapterEvent[], surface: readonly string[], message: string): Outage;
+export declare function whileBroken(events: readonly AdapterEvent[], message: string): Outage;
 /**
  * The one code `flow status` answers with.
  *
@@ -512,7 +571,11 @@ export declare function briefBlock(shown: readonly Shown[]): string;
  * moment. Exit 2 is the host's documented refusal channel and the model reads stderr on all three
  * rails, so flow has one refusal and one place to look when it fails to arrive.
  *
- * Injection stays the decision object, because there is no other channel for it.
+ * Injection stays the decision object, because there is no other channel for it — with one
+ * exception. Notes beside a refusal go on stderr after it: the host reads that stderr as the
+ * agent's next instruction, and its hooks reference says no JSON field on stdout can override an
+ * exit 2, so stderr is the one place both are sure to arrive. Only a held turn has any: before a
+ * call, the shell judges no notes once something refused (`ridesRefusal`).
  */
 export declare function toResult(hook: HookEvent, answer: Answer): HookResult;
 /**
@@ -535,25 +598,29 @@ export declare function refused(refusals: readonly Refused[], undone?: Undone):
 export declare function deltaFault(fault: string): HookResult;
 /** Hand the agent some context and allow — the one shape every steering rail emits. */
 export declare function decision(hook: HookEvent, additionalContext: string): string;
+/** The rails that run once a tool call has landed: their exit 2 reports, it cannot block. */
+export declare const AFTER_CALL: ReadonlySet<HookEvent>;
 /**
- * What the guard says when it could not read its own payload.
+ * The answer a rail gives when it could not read its payload — and which rails must be LOUD.
  *
  * The three outcomes of a read are not one outcome. "There was nothing to guard" is safe and common
  * — a hand-run, an empty stdin — and silence is the right answer to it. "I could not SEE what I was
  * guarding" is the old engine's invisible swallow: both were folded into `{}`, so a PreToolUse rail
- * holding an unreadable payload found no tool call, allowed, and told nobody. The sentence is the
- * same on every rail; what differs is whether the rail blocks with it, and that is the caller's
- * decision because it is a fact about what the event is FOR.
- */
-export declare function faultText(hook: HookEvent, why: "unreadable" | "unparseable", detail: string): string;
-/**
- * The answer a rail gives when it could not read its payload — and which rails must be LOUD.
+ * holding an unreadable payload found no tool call, allowed, and told nobody. So every rail says one
+ * fault line, and it keeps READ apart from PARSE: a payload that never arrived and one that arrived
+ * and was not JSON are different faults. The line names the hook and the cause, never "the guard",
+ * because on an after-call rail the call has already run and must not read as refused (#12).
  *
  * The three rails that judge a tool call answer exit 2: PreToolUse, where it refuses the call it
  * could not see, and the two after-call rails, where every change the call made is judged — there
- * exit 2 blocks nothing (the call has run) and puts the sentence in front of the model beside the
+ * exit 2 blocks nothing (the call has run) and puts the line in front of the model beside the
  * result, so a call whose changes went unjudged is never passed as clean. The rest only add a
  * breadcrumb or end a turn, and say it on stderr with exit 0.
+ *
+ * PreToolUse and the annotating rails print the line bare; an after-call rail wraps it in
+ * `deltaFault`, the one message for "flow could not see what this call changed", because the host
+ * labels its exit 2 a "blocking error" and the bare line read as a refusal of a call that had
+ * already landed (#12).
  */
 export declare function readFault(hook: HookEvent, why: "unreadable" | "unparseable", detail: string): HookResult;
 /** One line of a transcript, parsed. `record` is the raw object — this file reads it, nobody else. */
@@ -651,28 +718,31 @@ export declare function briefHead(jsonl: string, cap?: number): string;
  * outright — which is every repo's own first commit.
  */
 export declare function branchFromHead(head: string): string | null;
-/**
- * The sidecar beside a subagent's transcript: `…/agent-<id>.jsonl` → `…/agent-<id>.meta.json`.
- *
- * The host writes one for every spawn — present 335/335 in the probe — and it is the strongest
- * evidence in the system precisely because the session did not write it. A session could claim to
- * be anything, and permissions resting on the claim would rest on a lie.
- */
-export declare function sidecarPath(transcriptPath: string): string | null;
 /**
  * Host-written evidence about one session × agent, assembled — the shape a classifier sees.
  *
- * The sidecar's absence is itself the evidence for the top-level session: there is no positive
- * marker for being the parent, only the absence of having been spawned. A sidecar that will not
- * parse is NOT the same as none — the session was spawned, we simply cannot say as what — so
- * `subagent` stays true and `agentType` is left undefined, and a category keyed on a specific type
- * declines rather than the parent category wrongly claiming it.
+ * The payload's `agent_id` is what makes a call a subagent's, whether or not any file exists for
+ * it, and its `agent_type` is the type that subagent was started as. Both are in the message the
+ * host writes, which the session cannot change. A subagent whose message carries no type is
+ * spawned as something unknown: `subagent` stays true and `agentType` is left undefined, so a
+ * category keyed on a specific type declines rather than the parent category wrongly claiming it.
+ * The parent is recognised by ABSENCE — there is no positive marker for being the top-level
+ * session, only the absence of having been spawned.
+ *
+ * `transcript` is this agent's own transcript, a subagent's included, and its head is the brief.
  */
 export declare function sessionFactsFrom(args: {
     readonly payload: HookPayload;
     readonly transcript: string | null;
-    readonly sidecar: string | null;
 }): SessionFacts;
+/**
+ * Which agent one hook message came from — the one reading of it, for its state, its classification
+ * and its log rows alike.
+ *
+ * The type is read only beside an `agent_id`: the host also sends `agent_type` on a top-level
+ * session started with `--agent`, and that session is still the parent.
+ */
+export declare function agentOf(payload: HookPayload): AgentOf;
 /**
  * A tool call → the row that records it, or null when the payload names no tool at all.
  *
@@ -766,14 +836,24 @@ export declare function classifyStore(paths: readonly string[]): {
     transcripts: TranscriptRef[];
     ignored: string[];
 };
+/**
+ * The path of THIS agent's own transcript, from a live payload — null when the payload names none.
+ *
+ * On a subagent's call the host sends the PARENT's `transcript_path`, and keeps the subagent's own
+ * transcript under it, in the store's layout: `…/<session>.jsonl` →
+ * `…/<session>/subagents/agent-<agent_id>.jsonl`. The parent's path is the parent's transcript.
+ * Null too when a subagent's half is not what that layout needs — an id that could step out of the
+ * folder included, since it becomes part of a path that is then read.
+ */
+export declare function ownTranscriptPath(payload: HookPayload): string | null;
 /**
  * The sidecar the host writes beside every subagent transcript, read.
  *
  * `toolUseId` is the field that makes this more than a label: it is the id of the parent's own
- * `Agent` tool call, so a sidecar and the block that spawned it join exactly. That join is what
- * lets cost attribution and classification agree about who an actor was — the sidecar says what a
- * spawn WAS, the parent's block says when it happened and what it was asked for, and neither
- * alone answers both.
+ * `Agent` tool call, so a sidecar and the block that spawned it join exactly. That join names an
+ * actor for cost attribution, after the fact — the sidecar says what a spawn WAS, the parent's
+ * block says when it happened and what it was asked for, and neither alone answers both. A live
+ * session is not classified from it: that reads the agent type in its hook message.
  */
 export interface SpawnMeta {
     readonly agentType: string | null;
@@ -823,9 +903,10 @@ export interface Spawn {
  * Every spawn a parent transcript made, by tool_use id — the parent's half of the join.
  *
  * It is the WEAKER half and is read as such: what the parent asked for is a claim by the session
- * being classified, while the sidecar is host-written and unforgeable. The classification order
- * (engine, `spawnedAs`) reads the sidecar and never this. What this is for is everything the
- * sidecar cannot say — when the spawn happened, and where in the parent's own transcript to look.
+ * being classified, while the sidecar is host-written and unforgeable, and so outranks it here.
+ * Neither decides who a live session is: classification (engine, `spawnedAs`) reads the agent type
+ * in the hook message. What this is for is everything the sidecar cannot say — when the spawn
+ * happened, and where in the parent's own transcript to look.
  */
 export declare function spawnsIn(jsonl: string): Map<string, Spawn>;
 /** Text with terminal colour codes taken out — a recorded command line is full of them. */
@@ -871,7 +952,13 @@ export type TranscriptEvent = {
 export declare function parseEvents(jsonl: string, root?: string, home?: string): TranscriptEvent[];
 /** Does this prompt read as the human pushing back? */
 export declare function isCorrection(prose: string): boolean;
-/** The tools a repo's justfile actually drives — what a direct invocation would be bypassing. */
+/**
+ * The tools a repo's justfile actually drives — what a direct invocation would be bypassing.
+ *
+ * Each recipe's body is read through the parse as one script, so a loop or an `if` that spans its
+ * lines is read whole; a body that does not parse whole is read line by line, and a line that does
+ * not parse names nothing. Just's own `@` and `-` line prefixes are dropped first.
+ */
 export declare function recipeTools(justfile: string): string[];
 /** What one Bash line was: the recipes it drove, the tools it went round, and whether it committed. */
 export interface BashClass {
@@ -879,7 +966,12 @@ export interface BashClass {
     readonly bypasses: readonly string[];
     readonly commits: boolean;
 }
-/** Read one command line against the repo's own recipe tools. HEURISTIC, like everything below. */
+/**
+ * Read one command line against the repo's own recipe tools, from its parse. A heredoc's body is
+ * text the command is fed, so a file being written that names a tool is not a run of it — while
+ * the line around the heredoc is judged like any other, and so is a body a shell runs. A line that
+ * does not parse is nothing: no recipe, no bypass, no commit.
+ */
 export declare function classifyBash(command: unknown, tools: readonly string[]): BashClass;
 /** A pointer into a transcript — the shape every heuristic finding takes. */
 export interface Pointer {
@@ -955,12 +1047,16 @@ export declare function mergeNarratives(each: readonly {
     session: string;
     read: Narrative;
 }[]): Narrative;
+/**
+ * The repo's own Claude Code settings file, relative to the repo root: guarded here, and where
+ * `settingsFileFor` registers a dev dependency's hooks, and `flow uninstall` takes them out.
+ */
+export declare const REPO_SETTINGS = ".claude/settings.json";
 /**
  * The HOST's half of the guard: where the hooks that invoke any of it are registered.
  *
  * Fixed, because these are the harness's own file names and not a repo's choice — unlike the
- * repo's half, which is `configSurface` reading the config's imports. The old list spelled the two
- * halves as one constant, with one repo's pack folder standing in for every repo's.
+ * repo's half, which `guardPaths` reads out of the config's imports.
  *
  * THE GUARD PACK KEEPS ITS OWN, WIDER LIST, and the difference is deliberate — this is the one
  * place that says so, because two lists that look like copies are read as drift until somebody
@@ -980,7 +1076,18 @@ export declare function mergeNarratives(each: readonly {
  *     in, and that is the coupling the fence exists to prevent.
  */
 export declare const HOST_SURFACE: readonly string[];
-/** Every file that decides what the guard does here — the config and its packs, plus the host's. */
+/**
+ * Every file that decides what the guard does here: the config and the packs it imports, then the
+ * host's half. `weakenedAfterBlock` reads it — "a rail refused, and then somebody edited the guard".
+ *
+ * The repo's half is READ OUT OF THE CONFIG'S TEXT (`configImports`) rather than resolved, so it
+ * answers the same whether or not the config loads, and it follows whatever a repo called its pack
+ * folder — no folder name is spelled into the engine.
+ *
+ * The FOLDER of each imported pack comes with the file, which is the one deliberate widening. A
+ * pack imports its own helpers, and those the config never names. The import graph cannot be
+ * walked from text, so the folder is the honest approximation.
+ */
 export declare function guardPaths(configText: string | null): readonly string[];
 /** Is this one of the files that decides what the guard does? */
 export declare function isGuardPath(path: string, paths: readonly string[]): boolean;
@@ -1054,9 +1161,9 @@ export declare function health({ armed, rows, withRecord, analysed }: HealthArgs
  *
  * The sidecar says what a spawn WAS (`agentType`, unforgeable, written by the host) and the
  * parent's own `Agent` block says when it happened and what was asked for. Joining them on
- * `toolUseId` is what lets classification and cost attribution name the same actor: a builder
- * spawned under a generic bucket is `general-purpose` in the parent's claim and `builder` in the
- * host's record, and only one of those is evidence.
+ * `toolUseId` names an actor for cost attribution, after the fact: a builder spawned under a
+ * generic bucket is `general-purpose` in the parent's claim and `builder` in the host's record,
+ * and only one of those is evidence. A live session is classified from its hook message instead.
  */
 export interface SpawnRecord {
     /** The conversation that spawned it. */
@@ -1113,6 +1220,14 @@ export interface Steer {
  * of megabytes and the answer is one record.
  */
 export declare function steerOf(jsonl: string): Steer | null;
+/**
+ * The agent a session runs as (`--agent`, or the `agent` setting), from its own transcript — or
+ * null when it runs as none.
+ *
+ * The host writes it as an `agent-setting` record, again as the session goes on. Read from the END,
+ * and only lines that name the record are parsed, as `steerOf` does: the answer is one record.
+ */
+export declare function agentSettingOf(jsonl: string): string | null;
 /** The permission mode the last recorded call was made under, or null when no row states one. */
 export declare function lastMode(rows: readonly Row[]): string | null;
 /** The permission modes the read conversations ran under, and how many of them auto mode steered. */
@@ -1242,7 +1357,39 @@ export interface Registration {
     /** The host's `matcher`. Absent means every occurrence of the event. */
     readonly matcher?: string;
 }
+/**
+ * The repo's bin folder, relative to the repo root. flow never runs a `flow` from here: any package
+ * can install one (Facebook's `flow-bin` does), and nothing guards the folder. `hostPath` drops it
+ * from the PATH npm hands one run.
+ */
+export declare const LOCAL_BIN = "node_modules/.bin";
+/** Where the repo's own `@jawache/flow` is, relative to the repo root: a dev dependency, or init's link. */
+export declare const PACKAGE_DIR = "node_modules/@jawache/flow";
+/** That package's own binary — the file its `bin` names. */
+export declare const PACKAGE_BIN = "node_modules/@jawache/flow/dist/flow.mjs";
+/**
+ * The command each registration runs: the repo's own `@jawache/flow` first, then the PATH's.
+ *
+ * The host runs it through a shell with `$CLAUDE_PROJECT_DIR` set to the repo, so a repo with flow
+ * only as a dev dependency answers its hooks, and its lockfile's version wins over a global one. It
+ * runs the package's own file, by path, never a `flow` in node_modules/.bin, which any package can
+ * put there. The same command goes in either settings file, so the host, which merges identical
+ * commands, runs it once when it is in both.
+ */
+export declare function hookCommand(hook: HookEvent): string;
 export declare const HOOK_REGISTRATIONS: readonly Registration[];
+/**
+ * WHICH SETTINGS FILE holds flow's hooks: the repo's own `.claude/settings.json` when the repo's
+ * `package.json` lists `@jawache/flow` as a dependency or a dev dependency, and the machine-wide
+ * file otherwise.
+ *
+ * A dev dependency guards that one repo: the repo's file is committed, so a fresh clone is guarded
+ * after `npm install`, and a machine with no global flow is not handed a hook that fails in every
+ * other repo it opens. A `package.json` that is missing, or will not parse, lists nothing.
+ */
+export declare function settingsFileFor(manifest: string | null, machine: string): string;
+/** Does this `package.json` list `@jawache/flow` as a dependency or a dev dependency? */
+export declare function listsFlow(manifest: string | null): boolean;
 /**
  * Is this registration OURS?
  *
@@ -1265,17 +1412,54 @@ export declare function registeredEvents(settings: unknown): string[];
  */
 export declare function staleRegistrations(settings: unknown): string[];
 /**
- * A settings file with flow's registrations in it — a NEW object, and only ever added to.
+ * flow's own registration in the OLD shape, the bare `flow hook <event>`: the word it answers to, or
+ * null when the command is anything else. It finds flow on the PATH alone, so a repo with flow only
+ * as a dev dependency answers none of its hooks. A command with a path to the binary is not this
+ * shape: it names the copy it runs, and that is somebody's choice.
+ */
+export declare function bareHook(command: string): HookEvent | null;
+/** The events this settings file calls flow for in the old shape — see `bareHook`. */
+export declare function bareRegistrations(settings: unknown): string[];
+/**
+ * THE MACHINE-WIDE FILE, when a dev dependency's hooks are in the repo's own: flow's old-shape
+ * commands there (`bareHook`) rewritten to today's, and nothing else touched — no registration
+ * added, no matcher widened, no other key or hook changed. A NEW object; `rewritten` names the
+ * events, empty when there was nothing to do.
+ *
+ * The host merges only IDENTICAL commands across its settings files. An old `flow hook stop` in the
+ * machine-wide file beside today's command in the repo's would run flow twice for every event, so
+ * every rule would fire twice and every refusal print twice. Made the same command, it runs once.
+ */
+export declare function withMachineCommandsUpToDate(settings: unknown): {
+    settings: unknown;
+    rewritten: string[];
+};
+/**
+ * A settings file with flow's registrations in it — a NEW object, added to, and with flow's own
+ * entries brought up to date.
  *
- * It is somebody's file and holds far more than us, so nothing is rewritten and nothing is removed:
- * a registration on our event that belongs to another tool keeps its place and flow stands beside
- * it. Adding what is already there is skipped, which is the whole of what makes `flow init`
- * idempotent — a second run has nothing to say.
+ * It is somebody's file and holds far more than us, so nothing of anyone else's is rewritten and
+ * nothing is removed: a registration on our event that belongs to another tool keeps its place and
+ * flow stands beside it. Adding what is already there is skipped, which is the whole of what makes
+ * `flow init` idempotent — a second run has nothing to say.
  */
 export declare function withRegistrations(settings: unknown): {
     settings: unknown;
     added: string[];
 };
+/**
+ * A settings file with flow's registrations taken out — a NEW object, and the reverse of
+ * `withRegistrations`.
+ *
+ * On the events flow registers, each hook whose command is flow's (`ourHookCommand`, so an older
+ * flow's bare `flow hook <event>` goes too) is removed; an entry left with no hook goes, an event left
+ * with no entry goes, and a `hooks` key left empty goes. Every other key, event and hook is kept as
+ * it was. `removed` names the events, in registration order, empty when there was nothing of flow's.
+ */
+export declare function withoutRegistrations(settings: unknown): {
+    settings: unknown;
+    removed: string[];
+};
 /**
  * WHERE THE GATE LIVES, spelled once for everyone who names it.
  *
@@ -1289,24 +1473,139 @@ export declare const GATE_PATH = ".githooks/pre-commit";
 /** What arms git, said the way a person types it — the report's line and the fitting's fix. */
 export declare const SET_HOOKS_PATH = "git config core.hooksPath .githooks";
 /**
- * How to arm a gate flow will not write over, in the ONE wording both readers use.
+ * The gate's line that runs the repo's own `@jawache/flow` first: git runs the hook from the repo's
+ * root, so `$PWD` is the repo. Written by `init`, looked for by `status`, and named in its fixes.
+ */
+export declare const GATE_LOCAL_LINE: string;
+/** The gate's line that runs flow, last, so its exit code is the hook's. */
+export declare const GATE_RUN_LINE = "exec flow hook commit";
+/**
+ * How to arm a gate flow will not write over, in the ONE wording both readers use. Both of the
+ * gate's lines: the run line alone finds flow on the PATH alone, and a repo with flow only as a dev
+ * dependency then fails every commit.
  *
  * `init` says it about the hook it just declined to overwrite; `status` says it about the hook it
  * found unarmed. The same instruction, at the two moments a person can meet it — and two spellings
  * of an instruction are two instructions the day one of them is edited.
  */
-export declare const ADD_THE_GATE_LINE = "add `flow commit $(git diff --cached --name-only)` to it";
+export declare const ADD_THE_GATE_LINE: string;
+/**
+ * How to bring a gate written for the old verb up to date, in the ONE wording both readers use.
+ *
+ * The old hook still runs the gate, which is why it is not simply broken: it hands flow a list that
+ * leaves out deletions, and exits before calling flow at all when a commit only deletes files.
+ * `status` says that much; this is the instruction alone, so it ends `init`'s sentence cleanly.
+ */
+export declare const UPDATE_THE_GATE_LINE: string;
 /**
  * The pre-commit hook, verbatim.
  *
- * `flow commit <files…>` rather than a sixth hook, because the commit moment is not delivered by any
- * harness — git's own hook is what fires it, which is why every harness gets the gates for free. The
- * staged set is computed here rather than inside flow: it is git's own question, and this file is
- * already a git hook.
+ * `flow hook commit` — git's hook under the same verb as the harness's hooks. It passes nothing:
+ * flow asks git what the commit adds, changes and deletes, so there is one source of the staged set
+ * whoever calls the gate, and nothing in this file to filter it or to skip flow when it is empty.
  */
-export declare const PRE_COMMIT = "#!/bin/sh\n# The flow commit gate. Written by `flow init`; `git config core.hooksPath .githooks` arms it.\n#\n# Every at(commit) guardrail runs over the staged set and a block exits non-zero, which is how git\n# refuses the commit. This is the half of the promise the PreToolUse rail cannot make: it fires for\n# a human's commit, a merge and CI, with no session in the room.\nstaged=$(git diff --cached --name-only --diff-filter=ACMR)\n[ -z \"$staged\" ] && exit 0\n# shellcheck disable=SC2086\nexec flow commit $staged\n";
-/** Does this pre-commit hook call flow? Asked by `init` before writing, and by `status` after. */
+export declare const PRE_COMMIT: string;
+/** Does this pre-commit hook call flow's gate? Asked by `init` before writing, and by `status` after. */
 export declare function armsFlow(text: string | null): boolean;
+/** Does it call the gate's OLD verb, `flow commit` — a gate that runs, and misses deletions? */
+export declare function armsOldFlow(text: string | null): boolean;
+/**
+ * The pre-commit hook with flow taken out: `delete` when every command in it is one a `flow init`
+ * wrote, the hook less the lines that run flow when it holds commands of its own, and null when no
+ * line of it is flow's. A line is flow's only when it is, trimmed, exactly one flow wrote: a line
+ * somebody spelled themselves is theirs to remove.
+ */
+export declare function gateWithoutFlow(text: string | null): {
+    readonly delete: true;
+} | {
+    readonly delete: false;
+    readonly body: string;
+} | null;
+/**
+ * The lines of a hook that call flow, trimmed, in order: each line a `flow init` wrote into a gate
+ * or told a person to add, today's and every older release's, and any other line that runs
+ * `flow hook commit` or `flow commit`. Comments call nothing. What uninstall names for a person to
+ * delete from a hook that is not flow's to edit.
+ */
+export declare function flowLinesOf(text: string | null): string[];
+/** What the gate judges: the staged changes, or the whole tree as if all of it were staged. */
+export type CommitScope = "staged" | "all";
+/**
+ * `flow hook commit [--all]`, read. Null is a refusal: a file list here would be a second source of
+ * the staged set. `legacy` is the old `flow commit <files…>`, whose list an older hook still passes,
+ * and it is dropped rather than refused so that hook keeps running the gate.
+ */
+export declare function commitScope(args: readonly string[], legacy: boolean): CommitScope | null;
+/** The folder git runs hooks from, as the shell found it. One reading, for init and status alike. */
+export interface HooksFolder {
+    /** As git names it (`git rev-parse --git-path hooks`), spelled by `hooksDirOf`. */
+    readonly dir: string;
+    /** The name of every file in it, `.sample` files included: which of them count is decided here. */
+    readonly files: readonly string[];
+    /** The text of the pre-commit hook a person edits for that folder (`preCommitOf(dir)`), or null. */
+    readonly preCommitText: string | null;
+    /** That file has the execute bit this user needs to run it. False when there is no file. */
+    readonly preCommitExecutable: boolean;
+}
+/**
+ * What the pre-commit hook git runs lacks before it runs flow's gate: `add` flow's two lines;
+ * `create` the hook, which is not there; `chmod` a hook that calls flow but that git ignores,
+ * because it lacks the execute bit; or `add-and-chmod`, both.
+ */
+export type HookFix = "add" | "create" | "chmod" | "add-and-chmod";
+/** Git runs other hooks, and whether the pre-commit hook it runs calls flow. */
+export interface OtherHooks {
+    /** The folder git runs hooks from. */
+    readonly dir: string;
+    /** The pre-commit hook a person edits to call flow. */
+    readonly preCommit: string;
+    /** The first fix, or null when that hook calls flow's gate and git runs it: flow is installed. */
+    readonly fix: HookFix | null;
+}
+/** Other hooks that do not run flow's gate yet, so flow is not installed. */
+export type UnwiredHooks = OtherHooks & {
+    readonly fix: HookFix;
+};
+/** Does git run other hooks without flow's gate among them? */
+export declare function unwired(other: OtherHooks | null): other is UnwiredHooks;
+/**
+ * The pre-commit hook a person edits for this hooks folder.
+ *
+ * Usually the folder's own `pre-commit`. Husky is the exception: it points git at `.husky/_`, a
+ * folder of stubs it rewrites on every install, and each stub runs the hook of the same name one
+ * folder up, so the file a person edits is `.husky/pre-commit`. Any folder named `_` is read that way.
+ */
+export declare function preCommitOf(dir: string): string;
+/**
+ * The hooks folder as a person would type it, from git's answer to `git rev-parse --git-path hooks`
+ * run at the repo root: repo-relative when it is inside the repo, absolute when it is not, such as
+ * a worktree's shared `.git/hooks`. Resolved, so `.githooks/` and `./.githooks` both read `.githooks`.
+ */
+export declare function hooksDirOf(root: string, said: string): string;
+/**
+ * Does git run hooks other than flow's here? Null when it does not: `core.hooksPath` is flow's own
+ * folder, or it is unset and `.git/hooks` holds nothing but git's own `.sample` files. A
+ * `core.hooksPath` anywhere else counts whatever is in it, and any other file in `.git/hooks` counts,
+ * not only a `pre-commit`: Git LFS installs `pre-push` and `post-checkout` there.
+ */
+export declare function otherHooks(hooksPath: string | null, folder: HooksFolder): OtherHooks | null;
+/** The words the block opens with, fixed by the docs, for every reader that looks for them. */
+export declare const NOT_INSTALLED = "FLOW IS NOT INSTALLED";
+/**
+ * Git could not name the folder it runs hooks from, in the ONE wording init's report and status's
+ * line share. No advice: telling a husky repo to set `core.hooksPath` is what turns husky off.
+ */
+export declare const HOOKS_UNKNOWN = "git could not name the folder it runs hooks from, so flow cannot tell whether a commit runs its gate. Run `git rev-parse --git-path hooks` here to see why.";
+/** Other hooks whose pre-commit calls flow, in the ONE wording init's note and status's line share. */
+export declare function wiredLine(other: OtherHooks): string;
+/**
+ * The message for other hooks that do not run flow, in the ONE wording init's block and status's
+ * line share: the folder git runs hooks from, why its pre-commit hook does not run flow's gate, and
+ * the two ways to finish. The first fix is whatever that hook lacks: flow's two lines, the hook
+ * itself, or the execute bit. Init never takes either fix itself: editing or creating another
+ * tool's hook, or moving its hooks, is the person's call.
+ */
+export declare function notInstalledLines(other: UnwiredHooks): string[];
 /** The config file init writes: the demo, or the bare one `--empty` asks for. */
 export declare function scaffold(empty: boolean): string;
 /** What the shell found before anything was written. Every one is a stat, not a judgement. */
@@ -1321,8 +1620,11 @@ export interface InitFacts {
     readonly hasFlowDir: boolean;
     /** `git config core.hooksPath` as it stands. */
     readonly hooksPath: string | null;
+    /** The folder git runs hooks from, or null outside git or when git could not say. */
+    readonly hooksFolder: HooksFolder | null;
+    /** The settings file flow's hooks go in: the repo's own, repo-relative, or the machine-wide one. */
     readonly settingsPath: string;
-    /** The parsed host settings file. */
+    /** That file, parsed. */
     readonly settings: unknown;
     /**
      * The settings file is THERE and would not parse.
@@ -1334,6 +1636,15 @@ export interface InitFacts {
      * settings.json holding JSONC comments: the write was one branch away.
      */
     readonly settingsUnreadable: boolean;
+    /**
+     * The machine-wide settings file, read, when flow's hooks go in the repo's own file — a dev
+     * dependency's — and null when they go in the machine-wide file itself.
+     */
+    readonly machine: {
+        readonly path: string;
+        readonly settings: unknown;
+        readonly unreadable: boolean;
+    } | null;
     /** Does `@jawache/flow` already resolve from this repo? */
     readonly resolves: boolean;
     /**
@@ -1357,17 +1668,36 @@ export interface InitPlan {
     readonly gate: Write | null;
     /** A pre-commit hook that is somebody else's. Never overwritten — reported, with the line to add. */
     readonly gateKept: boolean;
+    /** …and it is flow's own, from before `flow hook commit` — reported with the line to replace. */
+    readonly gateOld: boolean;
     readonly notGit: boolean;
     readonly flowDir: boolean;
     /** The package to link into `node_modules/@jawache/flow`, or null when flow already resolves. */
     readonly link: string | null;
+    /** Point git at `.githooks`: a git repo whose git runs no other hooks, and not already there. */
     readonly hooksPath: boolean;
+    /** Git runs other hooks, so `core.hooksPath` is left alone. Flow is not installed unless it is wired. */
+    readonly otherHooks: OtherHooks | null;
+    /**
+     * A git repo whose git could not name the folder it runs hooks from, so `core.hooksPath` is left
+     * alone too: that folder may hold another tool's hooks, and setting it would turn them off.
+     */
+    readonly hooksUnknown: boolean;
     /** The rewritten settings, or null when they already call flow — or could not be read. */
     readonly settings: {
         readonly path: string;
         readonly value: unknown;
     } | null;
     readonly registered: readonly string[];
+    /**
+     * The machine-wide file with flow's old commands brought up to date, for a dev dependency whose
+     * hooks are in the repo's own file — or null when it has none, or could not be read.
+     */
+    readonly machine: {
+        readonly path: string;
+        readonly value: unknown;
+        readonly rewritten: readonly string[];
+    } | null;
     /** The settings file was there and would not parse, so nothing was registered. Said out loud. */
     readonly settingsUnreadable: string | null;
 }
@@ -1378,9 +1708,125 @@ export declare function planInit(facts: InitFacts): InitPlan;
  *
  * A setup command that prints "done" is a command nobody can check. Failures are handed in rather
  * than thrown because a PARTIAL init is the interesting case: the config landed, the settings file
- * was read-only, and the person needs to know exactly that.
+ * was read-only, and the person needs to know exactly that. `colour` is `wantsColour`'s answer for
+ * the output this is written to.
+ */
+export declare function initLines(plan: InitPlan, failures: readonly string[], colour?: boolean): string[];
+/**
+ * Does this output get colour? Only in a terminal, and never with `NO_COLOR` set to anything but an
+ * empty string, which is the convention at no-color.org. A pipe, a file and a test harness get the
+ * plain text, so nothing that reads the output has escape codes to strip.
  */
-export declare function initLines(plan: InitPlan, failures: readonly string[]): string[];
+export declare function wantsColour(terminal: boolean, noColor: string | undefined): boolean;
+/**
+ * Init's exit code. 1 when it could not finish, and 1 when flow is not installed or cannot tell: a
+ * script chaining `flow init && …` is asking whether the repo is guarded, and a gate git never runs
+ * is not.
+ */
+export declare function initCode(plan: InitPlan, failures: readonly string[]): 0 | 1;
+/** What the shell found before anything was removed. Every one is a stat, not a judgement. */
+export interface UninstallFacts {
+    readonly hasConfig: boolean;
+    /** The gate as it stands, or null when there is none. */
+    readonly gateText: string | null;
+    /** `git config core.hooksPath` as it stands. */
+    readonly hooksPath: string | null;
+    /** The repo's top folder when the run is in a folder below it, else null. */
+    readonly subfolderOf: string | null;
+    /** The names in `.githooks/`, or null when there is no such folder. */
+    readonly hooksDir: readonly string[] | null;
+    /**
+     * The folder git runs hooks from, read at the repo's top folder as init and status read it, or
+     * null outside git or when git could not say.
+     */
+    readonly hooksFolder: HooksFolder | null;
+    readonly hasFlowDir: boolean;
+    /** `node_modules/@jawache/flow` is a symlink: the link `flow init` makes. A real folder is an install. */
+    readonly linked: boolean;
+    /** Does the repo's `package.json` list `@jawache/flow`? Then flow's hooks are in the repo's own settings file. */
+    readonly listed: boolean;
+    /** The repo's `.claude/settings.json`, parsed; null when there is none. */
+    readonly settings: unknown;
+    /** …it is there and would not parse. */
+    readonly settingsUnreadable: boolean;
+    /** `--machine` was given: the machine-wide settings file is flow's to clean too. */
+    readonly machineFlag: boolean;
+    /** The machine-wide settings file: its absolute path, its JSON (null when there is none), and whether it would not parse. */
+    readonly machineFile: {
+        readonly path: string;
+        readonly settings: unknown;
+        readonly unreadable: boolean;
+    };
+}
+/** A settings file with flow's registrations taken out: where it is, what to write, and the events that went. */
+export interface SettingsWithout {
+    readonly path: string;
+    readonly value: unknown;
+    readonly removed: readonly string[];
+}
+/** Everything `flow uninstall` will do, decided before a byte is removed. */
+export interface UninstallPlan {
+    /** The gate: deleted, rewritten without flow's lines, or null when nothing in it is flow's. */
+    readonly gate: {
+        readonly path: string;
+        readonly body: string | null;
+    } | null;
+    /**
+     * A pre-commit hook that still calls flow after the run, in lines flow did not write there: that
+     * hook, as the report names it, and those lines, for a person to delete before `npm uninstall`.
+     * The hook git runs from another folder, such as husky's `.husky/pre-commit`, which uninstall
+     * never edits, as `flow init` never does; else what is left of `.githooks/pre-commit`. Null when
+     * neither calls flow.
+     */
+    readonly hookCallsFlow: {
+        readonly path: string;
+        readonly lines: readonly string[];
+    } | null;
+    /** Unset `core.hooksPath`: it is `.githooks`, the run is at the repo's top folder, and the folder holds no other hook. */
+    readonly hooksPath: boolean;
+    /**
+     * `core.hooksPath` is `.githooks` but the run is in a subfolder: the repo's top folder, where
+     * `flow uninstall` removes it, or null.
+     */
+    readonly hooksPathFrom: string | null;
+    /** The hooks that keep `core.hooksPath` at `.githooks`, named for the report. */
+    readonly hooksKept: readonly string[];
+    /** Remove `.githooks/`, which nothing else is in. */
+    readonly hooksDir: boolean;
+    readonly flowDir: boolean;
+    readonly link: boolean;
+    /** The repo's settings file without flow's registrations, or null when it holds none. */
+    readonly settings: SettingsWithout | null;
+    /** With `--machine`: the machine-wide settings file without flow's registrations, or null when it holds none. */
+    readonly machine: SettingsWithout | null;
+    /** The settings files flow's to clean that would not parse: nothing written to them, each said out loud. */
+    readonly unreadable: readonly string[];
+    /** How this run was typed, so a failure's report says what to run again. */
+    readonly command: string;
+    readonly keptConfig: boolean;
+    /**
+     * The machine-wide file this repo's hooks are in still holds them, because `--machine` was not
+     * given: its path, said beside the report and in its last line, or null. Without it, a plain run
+     * reports success while every Claude Code session on the machine still calls `flow`.
+     */
+    readonly machineHolds: string | null;
+    /** The command that removes the package, the report's last line. */
+    readonly next: string;
+}
+/** What uninstall will remove from this repo. Pure: every branch reads a fact the shell already gathered. */
+export declare function planUninstall(facts: UninstallFacts): UninstallPlan;
+/** The one argument `flow uninstall` takes: clean the machine-wide settings file too. */
+export declare const MACHINE_FLAG = "--machine";
+/**
+ * `flow uninstall`'s arguments, read: null when they are fine, else the refusal to print. An argument
+ * it does not know is refused rather than ignored, because this verb deletes files and a `--dry-run`
+ * or a `--help` that went ahead would delete them too.
+ */
+export declare function uninstallRefusal(args: readonly string[]): string | null;
+/** A step that could not be done answers 1, whether the shell hit it or the plan did. */
+export declare function uninstallCode(plan: UninstallPlan, failures: readonly string[]): 0 | 1;
+/** The report: every removal named, what was kept and why, each failure, and the command to run next. */
+export declare function uninstallLines(plan: UninstallPlan, failures: readonly string[]): string[];
 /** One thing the world around the config has to be, and whether it is. A red line carries its fix. */
 export interface Fitting {
     readonly id: string;
@@ -1398,8 +1844,18 @@ export interface StatusFacts {
     readonly load: LoadResult | null;
     readonly gateText: string | null;
     readonly hooksPath: string | null;
+    /** The folder git runs hooks from, read as init reads it, or null outside git or when git could not say. */
+    readonly hooksFolder: HooksFolder | null;
     readonly settingsPath: string;
     readonly settings: unknown;
+    /**
+     * The machine-wide settings file, parsed, when flow's hooks are in the repo's own file — a dev
+     * dependency's — and null when `settingsPath` is the machine-wide file itself.
+     */
+    readonly machine: {
+        readonly path: string;
+        readonly settings: unknown;
+    } | null;
     /**
      * The grammars the config declared, each with its library path made absolute and a straight
      * answer about whether that file is there.
@@ -1432,6 +1888,18 @@ export interface StatusFacts {
     readonly ignored: readonly string[];
     /** The config's `snapshotInclude` globs: the ignored paths the snapshot records anyway. */
     readonly snapshotInclude: readonly string[];
+    /**
+     * Where the flow the hooks and the gate run is, as three stats. `listed`: the repo's
+     * `package.json` lists `@jawache/flow`. `copy`: its package's binary, `PACKAGE_BIN`, is there —
+     * a dev dependency's, or the link `flow init` made to the flow that ran it. `path`: a `flow` on
+     * the PATH this command was run with, less what npm added for this run (`hostPath`) — the nearest
+     * reading there is of the PATH git and the host hand their hooks. `binaryFitting` judges them.
+     */
+    readonly binary: {
+        readonly listed: boolean;
+        readonly copy: boolean;
+        readonly path: boolean;
+    };
 }
 /**
  * The literal head of a glob, cut back to a whole segment: `src/gen/**` → `src/gen/`, `.env` →
@@ -1475,6 +1943,15 @@ export interface Status {
     readonly refusals: readonly Refusal[];
     readonly green: boolean;
 }
+/**
+ * THE PATH GIT AND THE HOST HAND THEIR HOOKS, read off the PATH this command was run with: every
+ * folder of it but a `node_modules/.bin` that npm put there for this one run — the repo's own or an
+ * ancestor's, which `npx flow` and `npm run` add, and npx's cache of a package it fetched. Counted,
+ * `npx flow status` would find a dev dependency's copy "on the PATH" that git never sees.
+ *
+ * Another repo's node_modules/.bin stays: it is on the PATH because someone put it there.
+ */
+export declare function hostPath(dirs: readonly string[], root: string): string[];
 /** Does this adapter carry that moment, for that KIND of entry? */
 export declare function delivers(kind: EntrySpec["kind"], moment: Moment): boolean;
 /** The gathered facts, judged. Never throws: a broken config is a red line, not an exception. */