@cerebriline/core 4.100.274 → 4.100.276

package/dist/extensions/config/prompt-template-review.d.ts

@@ -1,7 +1,7 @@
 import { type PromptTemplate } from "@cerebriline/shared";
 import { type CompactionPromptSources } from "./prompt-template-compaction";
 export declare const DEFAULT_REQUIRED_REWRITES: readonly ["read_files", "search_codebase", "editor", "apply_patch", "run_commands", "fetch_web_content", "check_file", "ask_lsp", "grep", "sed", "awk"];
-export declare const PROMPT_TEMPLATE_REVIEW_INSTRUCTIONS = "You are being shown the prompt Cline gives you when it uses you as a coding agent: a system prompt and a set of tool descriptions. You are the intended reader of this text. Rewrite it into the form you would rather receive.\n\nThis is not a copy-editing task. The prompt below was written by someone reasoning about how you read, and they may have been wrong. Where a section is phrased in a way you would skim, reorder or restate it. Where a rule matters and is buried, put it where you would be when you are about to break it. Where something is repeated to no effect, cut it.\n\nFour failures are observed in practice with models in your family, and the rewrite is judged on whether it prevents them:\n\n1. Reaching for shell commands to do file work \u2014 'cat' to read, 'sed -i' or 'echo >' to write, 'grep' to search \u2014 when dedicated tools exist and are always available.\n2. Serialising independent work across turns: one read, wait, one read, wait, when all of them were known at the start.\n3. Announcing an intention instead of acting on it, or claiming a task is finished without reading back what was written.\n4. Answering a question about a symbol with a text search. Asking where something is defined, what uses it, what implements it, or what a name means, and then grepping for it and reading several files to work out which hit was the real one \u2014 when the IDE's language servers already know the answer exactly and will give it in one call. The same failure in its other form: running a compiler or a linter through the shell to find out whether one file is valid, and waiting for a whole-project build to answer a one-file question.\n\nOne thing you must get right, and which prompts written for this get wrong in both directions:\n\nA coding agent is multi-turn, and the end of a turn is never in itself the end of the work. What is final is the completion of the assigned work \u2014 the task, the work package, the milestone, the request. An end of turn may be a milestone reached, a point where you need direction, guidance or a clarification from the user, or simply an intermediate step between two things the user asked for. So:\n\n- Do not treat \"I have stopped emitting tool calls\" as \"the work is done\". It is not a signal about the work at all.\n- Do not write a rule that makes stopping feel like failure, such as \"a response without a tool call is considered complete\". A rule like that buys one more unnecessary tool call on every finished task, and it teaches the wrong thing: that continuing is always correct.\n- Keep your attention on the long horizon of the assigned work rather than on the current turn. Ending a turn to ask a question is correct when you need the answer. Ending it while work you were asked to do remains untouched, and saying nothing about that, is not.\n\nFour more things are settled by measurement rather than by opinion, and a rewrite is judged on whether it keeps them:\n\n- The checker and the run belong in the same turn. Call 'check_file' and the thing that executes the code - 'run_commands', or 'browser' for a page - together, not one or the other. Running it says *that* something is broken and where the parser gave up; the checker says *which line* to edit. Each is half the answer, and the half you skip is the half the turn gets spent guessing at.\n- A tool's report outranks your own reasoning about the same question. Where a tool has measured something - a delimiter scan naming the line to edit, a diagnostic naming a type - that is the measurement, and re-deriving it yourself is an estimate. Where the two disagree, it is the estimate that is wrong. Measured twice: a model called a delimiter scan a false positive, counted brackets by hand instead, and was wrong both times, at over 30,000 thinking tokens a turn. If you doubt a report, do not re-derive it - act on it and run the result. That costs milliseconds and settles it either way.\n- Make the planned changes one at a time, and confirm each one before starting the next. The cheap check that does not execute the code goes after every edit; the thing that runs the code is what settles whether the change was right. Six edits made together and checked once leave six things to undo and no way to tell which one was wrong - measured across ten runs, the template that said otherwise drew 13.6 'restore_file' calls per run against 0.23 for the family that did not.\n- Do not re-read a file to confirm your own edit. The edit call already reports whether it landed and what changed, and that is the confirmation. Measured on one session: 'read_files' was called 33 times, 31 of them byte-identical, returning 440,013 characters against a file of 14 KB - four times the tokens that session spent on all of its reasoning. Read again when the call failed, or when you need content you have not seen. A rule that says to read a file back after every edit is the one thing here you must not write.\n\nHard constraints:\n\n- Keep every placeholder exactly as written, including the braces: {{PLATFORM_NAME}}, {{CURRENT_DATE}}, {{IDE_NAME}}, {{CWD}}, {{CLINE_RULES}}, {{CLINE_METADATA}}, {{DEFAULT}}. They are substituted at runtime; a renamed or dropped placeholder breaks the prompt.\n- Keep the tool names exactly as written. They are the wire names of real tools.\n- Do not invent tools, parameters, or capabilities. Describe only what is described below.\n- Keep the file structure: YAML frontmatter between --- markers, then '# system', then one '# tool: <name>' section for EVERY tool listed below. Not only the ones you want to change \u2014 every one of them.\n- Covering every tool is a hard requirement. A tool with no section keeps its built-in description, and that fallback exists for exactly one situation: Cline gains a new tool and the templates have not been regenerated yet. It is not a way to skip tools you have nothing to say about. A template that covers six of thirty-one tools is not using the fallback, it is relying on it, and nothing in the file shows which twenty-five were left out.\n- '{{DEFAULT}}' expands to the tool's built-in description at runtime, and it is how you cover a tool cheaply. Where you would improve on the built-in wording, write your own and put '{{DEFAULT}}' on its own line where the built-in text should follow. Where you would not, the entire section body may be just '{{DEFAULT}}'. Either is a covered tool; an absent section is not.\n- Text you write beside '{{DEFAULT}}' is sent in addition to the built-in description, not instead of it, on every request. So write only what you add: the rule a model in your family breaks, the case it misreads, the one example that settles it. Do not restate or paraphrase what the built-in text already says; it follows anyway, and a restatement means the reader takes in the same thing twice. If you want to say everything in your own words, drop '{{DEFAULT}}' and write the whole description instead.\n- These eight tools must be written in your own words, and a section containing only '{{DEFAULT}}' is not acceptable for any of them: read_files, search_codebase, editor, apply_patch, run_commands, fetch_web_content, check_file, ask_lsp. They are the tools models in your family are observed to misuse, so they are the whole reason this template exists. For these eight, your own text \u2014 not the inherited text \u2014 has to carry the three things listed below: every value of any closed set, every argument and when to use it, and what comes back. Adding '{{DEFAULT}}' after your text is allowed and does not excuse you from any of that.\n- For 'ask_lsp', say when to reach for it, not only what it does. List at least three concrete situations as the reader actually meets them \u2014 \"about to search for a name to find where it is defined\", \"about to open a file just to read a signature\", \"about to scroll or count brackets to work out a file's structure\" \u2014 each pointing at the operation that answers it, and name 'search_codebase' as the thing those situations would otherwise go to. This is not padding: measured across a whole session against a real bug, a template that described all eight operations correctly and said only \"prefer this over search_codebase for anything about a symbol\" produced zero calls to the tool, while the model hand-rolled the same answers in the shell twenty times. It could not recognise the moment.\n- Do not copy a built-in description out word for word. That is a snapshot: it says the same thing today and stops tracking the built-in text tomorrow, so the next edit to it reaches every model except you. If you would not change the wording, write '{{DEFAULT}}' \u2014 that is what it is for.\n- Where you rule a use of a tool out, name the tool that replaces it. 'run_commands' in particular must name 'read_files', 'editor' and 'search_codebase' in your own text: \"do not use this for file operations when dedicated tools exist\" is a rule the reader has to already know the answer to in order to follow, which is the same as not writing it.\n- Two of those eight \u2014 'run_commands' and 'skills' \u2014 must keep '{{DEFAULT}}' in the section as well. Their built-in descriptions are not fixed text: 'run_commands' is composed against the shell that will actually run the commands, so PowerShell, cmd and a POSIX shell get different quoting and sequencing advice, and 'skills' appends the skills installed on that machine. Replace either outright and you freeze one machine's answer into every machine's prompt, silently. Write your own text and put '{{DEFAULT}}' on its own line where the built-in text should follow.\n- For the other tools, a section whose body is exactly '{{DEFAULT}}' is a complete and correct answer. Do not pad them. Nothing about how you read changes what 'team_finalize_outcome' should say.\n- Emit every section exactly once. Do not repeat '# system', and do not write two '# tool: <name>' headings for the same tool. Only the last copy of a repeated section survives, so a duplicate silently throws away your own work.\n- Leave the 'match:' block in the frontmatter exactly as it is. It is what routes this template to you; change it and your rewrite reaches a different model, or none.\n\nReplace a description and you inherit everything it was carrying:\n\nIf a '# tool:' section contains '{{DEFAULT}}' anywhere, the built-in description is still delivered and you are only adding emphasis on top of it. Nothing further is asked of you for that tool \u2014 unless it is one of the eight above, which are judged on your words alone.\n\nIf it does not, your text is the only thing a model will ever see about that tool, so it must not lose what the built-in description said. Specifically, and only where the built-in text below says it:\n\n1. Closed sets. Where the built-in description lists the values an argument accepts \u2014 the operations of a language-server tool, the actions of a task tool, the statuses of a run \u2014 your replacement must list all of them too. Naming four of eight hides half the tool and a model cannot guess the rest.\n2. How to address the tool. Where the built-in description names the arguments, and says which one to use when, your replacement must say the same. A tool that can be addressed three ways needs all three, and what each is for.\n3. What comes back. Where the built-in description states an output, your replacement must state one: what each entry is named by, what it holds, and what an empty or failed result means. A model that cannot map a result back onto its request spends a turn working it out, and then stops trusting the tool. Say it in words, as the built-in text does: do not name fields such as 'query', 'result' or 'success', and do not write the result as an object like '{query, result, success, error?}'. A session receives tool results as text or as JSON, chosen when it starts, so a description of one format is false in the other.\n\nNothing is required of you that the built-in text did not already provide. Reproducing what is there is always enough; improving on it is better; dropping it is the one thing that is not allowed.\n\nDo not write 'Output:' followed by nothing, or by a single word. An empty label reads as an empty result, which is worse than saying nothing at all.\n\nFor any tool outside the eight, if restating all of that is not worth it to you, do not replace its description. Write your emphasis and leave '{{DEFAULT}}' in the section, or write nothing but the marker. That is cheaper and it is always correct.\n\nReply with the complete template file and nothing else: no preamble, no explanation, no code fence.";
+export declare const PROMPT_TEMPLATE_REVIEW_INSTRUCTIONS = "You are being shown the prompt Cline gives you when it uses you as a coding agent: a system prompt and a set of tool descriptions. You are the intended reader of this text. Rewrite it into the form you would rather receive.\n\nThis is not a copy-editing task. The prompt below was written by someone reasoning about how you read, and they may have been wrong. Where a section is phrased in a way you would skim, reorder or restate it. Where a rule matters and is buried, put it where you would be when you are about to break it. Where something is repeated to no effect, cut it.\n\nFour failures are observed in practice with models in your family, and the rewrite is judged on whether it prevents them:\n\n1. Reaching for shell commands to do file work \u2014 'cat' to read, 'sed -i' or 'echo >' to write, 'grep' to search \u2014 when dedicated tools exist and are always available.\n2. Serialising independent work across turns: one read, wait, one read, wait, when all of them were known at the start.\n3. Announcing an intention instead of acting on it, or claiming a task is finished without reading back what was written.\n4. Answering a question about a symbol with a text search. Asking where something is defined, what uses it, what implements it, or what a name means, and then grepping for it and reading several files to work out which hit was the real one \u2014 when the IDE's language servers already know the answer exactly and will give it in one call. The same failure in its other form: running a compiler or a linter through the shell to find out whether one file is valid, and waiting for a whole-project build to answer a one-file question.\n\nOne thing you must get right, and which prompts written for this get wrong in both directions:\n\nA coding agent is multi-turn, and the end of a turn is never in itself the end of the work. What is final is the completion of the assigned work \u2014 the task, the work package, the milestone, the request. An end of turn may be a milestone reached, a point where you need direction, guidance or a clarification from the user, or simply an intermediate step between two things the user asked for. So:\n\n- Do not treat \"I have stopped emitting tool calls\" as \"the work is done\". It is not a signal about the work at all.\n- Do not write a rule that makes stopping feel like failure, such as \"a response without a tool call is considered complete\". A rule like that buys one more unnecessary tool call on every finished task, and it teaches the wrong thing: that continuing is always correct.\n- Keep your attention on the long horizon of the assigned work rather than on the current turn. Ending a turn to ask a question is correct when you need the answer. Ending it while work you were asked to do remains untouched, and saying nothing about that, is not.\n\nFour more things are settled by measurement rather than by opinion, and a rewrite is judged on whether it keeps them:\n\n- The checker and the run belong in the same turn. Call 'check_file' and the thing that executes the code - 'run_commands', or 'browser' for a page - together, not one or the other. Running it says *that* something is broken and where the parser gave up; the checker says *where*: the line the parser stops on and the lines where brackets stop pairing. Each is half the answer, and the half you skip is the half the turn gets spent guessing at.\n- A tool's report outranks your own reasoning about the same question. Where a tool has measured something - a delimiter scan naming where brackets stop pairing, a diagnostic naming a type - that is the measurement, and re-deriving it yourself is an estimate. Where the two disagree, it is the estimate that is wrong. Measured twice: a model called a delimiter scan a false positive, counted brackets by hand instead, and was wrong both times, at over 30,000 thinking tokens a turn. If you doubt a report, do not re-derive it - act on it and run the result. That costs milliseconds and settles it either way.\n- Make the planned changes one at a time, and confirm each one before starting the next. The cheap check that does not execute the code goes after every edit; the thing that runs the code is what settles whether the change was right. Six edits made together and checked once leave six things to undo and no way to tell which one was wrong - measured across ten runs, the template that said otherwise drew 13.6 'restore_file' calls per run against 0.23 for the family that did not.\n- Do not re-read a file to confirm your own edit. The edit call already reports whether it landed and what changed, and that is the confirmation. Measured on one session: 'read_files' was called 33 times, 31 of them byte-identical, returning 440,013 characters against a file of 14 KB - four times the tokens that session spent on all of its reasoning. Read again when the call failed, or when you need content you have not seen. A rule that says to read a file back after every edit is the one thing here you must not write.\n\nHard constraints:\n\n- Keep every placeholder exactly as written, including the braces: {{PLATFORM_NAME}}, {{CURRENT_DATE}}, {{IDE_NAME}}, {{CWD}}, {{CLINE_RULES}}, {{CLINE_METADATA}}, {{DEFAULT}}. They are substituted at runtime; a renamed or dropped placeholder breaks the prompt.\n- Keep the tool names exactly as written. They are the wire names of real tools.\n- Do not invent tools, parameters, or capabilities. Describe only what is described below.\n- Keep the file structure: YAML frontmatter between --- markers, then '# system', then one '# tool: <name>' section for EVERY tool listed below. Not only the ones you want to change \u2014 every one of them.\n- Covering every tool is a hard requirement. A tool with no section keeps its built-in description, and that fallback exists for exactly one situation: Cline gains a new tool and the templates have not been regenerated yet. It is not a way to skip tools you have nothing to say about. A template that covers six of thirty-one tools is not using the fallback, it is relying on it, and nothing in the file shows which twenty-five were left out.\n- '{{DEFAULT}}' expands to the tool's built-in description at runtime, and it is how you cover a tool cheaply. Where you would improve on the built-in wording, write your own and put '{{DEFAULT}}' on its own line where the built-in text should follow. Where you would not, the entire section body may be just '{{DEFAULT}}'. Either is a covered tool; an absent section is not.\n- Text you write beside '{{DEFAULT}}' is sent in addition to the built-in description, not instead of it, on every request. So write only what you add: the rule a model in your family breaks, the case it misreads, the one example that settles it. Do not restate or paraphrase what the built-in text already says; it follows anyway, and a restatement means the reader takes in the same thing twice. If you want to say everything in your own words, drop '{{DEFAULT}}' and write the whole description instead.\n- These eight tools must be written in your own words, and a section containing only '{{DEFAULT}}' is not acceptable for any of them: read_files, search_codebase, editor, apply_patch, run_commands, fetch_web_content, check_file, ask_lsp. They are the tools models in your family are observed to misuse, so they are the whole reason this template exists. For these eight, your own text \u2014 not the inherited text \u2014 has to carry the three things listed below: every value of any closed set, every argument and when to use it, and what comes back. Adding '{{DEFAULT}}' after your text is allowed and does not excuse you from any of that.\n- For 'ask_lsp', say when to reach for it, not only what it does. List at least three concrete situations as the reader actually meets them \u2014 \"about to search for a name to find where it is defined\", \"about to open a file just to read a signature\", \"about to scroll or count brackets to work out a file's structure\" \u2014 each pointing at the operation that answers it, and name 'search_codebase' as the thing those situations would otherwise go to. This is not padding: measured across a whole session against a real bug, a template that described all eight operations correctly and said only \"prefer this over search_codebase for anything about a symbol\" produced zero calls to the tool, while the model hand-rolled the same answers in the shell twenty times. It could not recognise the moment.\n- Do not copy a built-in description out word for word. That is a snapshot: it says the same thing today and stops tracking the built-in text tomorrow, so the next edit to it reaches every model except you. If you would not change the wording, write '{{DEFAULT}}' \u2014 that is what it is for.\n- Where you rule a use of a tool out, name the tool that replaces it. 'run_commands' in particular must name 'read_files', 'editor' and 'search_codebase' in your own text: \"do not use this for file operations when dedicated tools exist\" is a rule the reader has to already know the answer to in order to follow, which is the same as not writing it.\n- Two of those eight \u2014 'run_commands' and 'skills' \u2014 must keep '{{DEFAULT}}' in the section as well. Their built-in descriptions are not fixed text: 'run_commands' is composed against the shell that will actually run the commands, so PowerShell, cmd and a POSIX shell get different quoting and sequencing advice, and 'skills' appends the skills installed on that machine. Replace either outright and you freeze one machine's answer into every machine's prompt, silently. Write your own text and put '{{DEFAULT}}' on its own line where the built-in text should follow.\n- For the other tools, a section whose body is exactly '{{DEFAULT}}' is a complete and correct answer. Do not pad them. Nothing about how you read changes what 'team_finalize_outcome' should say.\n- Emit every section exactly once. Do not repeat '# system', and do not write two '# tool: <name>' headings for the same tool. Only the last copy of a repeated section survives, so a duplicate silently throws away your own work.\n- Leave the 'match:' block in the frontmatter exactly as it is. It is what routes this template to you; change it and your rewrite reaches a different model, or none.\n\nReplace a description and you inherit everything it was carrying:\n\nIf a '# tool:' section contains '{{DEFAULT}}' anywhere, the built-in description is still delivered and you are only adding emphasis on top of it. Nothing further is asked of you for that tool \u2014 unless it is one of the eight above, which are judged on your words alone.\n\nIf it does not, your text is the only thing a model will ever see about that tool, so it must not lose what the built-in description said. Specifically, and only where the built-in text below says it:\n\n1. Closed sets. Where the built-in description lists the values an argument accepts \u2014 the operations of a language-server tool, the actions of a task tool, the statuses of a run \u2014 your replacement must list all of them too. Naming four of eight hides half the tool and a model cannot guess the rest.\n2. How to address the tool. Where the built-in description names the arguments, and says which one to use when, your replacement must say the same. A tool that can be addressed three ways needs all three, and what each is for.\n3. What comes back. Where the built-in description states an output, your replacement must state one: what each entry is named by, what it holds, and what an empty or failed result means. A model that cannot map a result back onto its request spends a turn working it out, and then stops trusting the tool. Say it in words, as the built-in text does: do not name fields such as 'query', 'result' or 'success', and do not write the result as an object like '{query, result, success, error?}'. A session receives tool results as text or as JSON, chosen when it starts, so a description of one format is false in the other.\n\nNothing is required of you that the built-in text did not already provide. Reproducing what is there is always enough; improving on it is better; dropping it is the one thing that is not allowed.\n\nDo not write 'Output:' followed by nothing, or by a single word. An empty label reads as an empty result, which is worse than saying nothing at all.\n\nFor any tool outside the eight, if restating all of that is not worth it to you, do not replace its description. Write your emphasis and leave '{{DEFAULT}}' in the section, or write nothing but the marker. That is cheaper and it is always correct.\n\nReply with the complete template file and nothing else: no preamble, no explanation, no code fence.";
 export declare function buildPromptTemplateReviewPrompt(defaultTemplate: string, familyTemplate: string | undefined, familyTemplateName: string | undefined, 
 /** What this model is, so a new template can be told how to claim itself. */
 target?: {

package/dist/extensions/tools/ask-lsp.d.ts

@@ -35,7 +35,7 @@ import { type AgentTool } from "@cerebriline/shared";
 export declare const ASK_LSP_TOOL_NAME = "ask_lsp";
 export declare const ASK_LSP_OPERATIONS: readonly ["definition", "references", "implementations", "type_definition", "hover", "document_symbols", "workspace_symbols", "callers"];
 export type AskLspOperation = (typeof ASK_LSP_OPERATIONS)[number];
-export declare const ASK_LSP_TOOL_DESCRIPTION = "Ask the language servers \u2014 the LSP \u2014 about a symbol. If you are reaching for an LSP tool or an MCP server that wraps one, this is it: the same protocol, already running against this workspace and its open files, with no server to start. This answers questions a text search cannot, because it understands the code: it distinguishes a definition from a mention, and this class's method from another class's method of the same name.\n\nUse this before falling back to `search_codebase` for anything about a symbol. It is faster, exact, and does not need you to read files to interpret the result.\n\nReach for it the moment you are about to do one of these by hand:\n- search for a name to find where it is defined -> `definition`\n- search for a name to find what uses it, or what would break -> `references` or `callers`\n- open a file just to read a signature, type or doc comment -> `hover`\n- scroll a file, or count brackets, to work out its structure -> `document_symbols`\n- grep the repo to find which file something lives in -> `workspace_symbols`\n\nOperations:\n- `definition` \u2014 where a symbol is defined.\n- `references` \u2014 every place it is actually used.\n- `implementations` \u2014 the classes or functions implementing an interface or abstract method.\n- `type_definition` \u2014 where the type of an expression is defined.\n- `hover` \u2014 the signature, type and documentation, as an editor shows on hover.\n- `document_symbols` \u2014 an outline of one file: its classes, functions and methods.\n- `workspace_symbols` \u2014 find a symbol by name across the whole project when you do not know which file it is in.\n- `callers` \u2014 what calls this function.\n\nHow to address a symbol:\n- Usually: `path` plus `symbol` \u2014 the name as it appears in that file.\n- If you know the exact position: `path`, `line` and `character` (both 1-based).\n- If you do not know the file: `symbol` alone, with `operation: \"workspace_symbols\"`.\n\nOutput: plain text, one result per line as `file:line:column` followed by that source line, so you can go straight to the one you want rather than reading each candidate. `hover` returns the signature and documentation as text instead, and `document_symbols` and `workspace_symbols` name each symbol's kind.\n\nAn empty answer is a real answer once the symbol resolved: for `definition`, `references`, `implementations`, `type_definition`, `callers` and `hover` the server understood the symbol and nothing matched, so a text search for the same question will not find more. `workspace_symbols` is the exception, and says so when it comes back empty: it reads a project-wide index that covers the languages a server is installed for and does not index script embedded in `.html` or other template files, so nothing there is not proof of nothing anywhere. And when the file does not parse, every answer about it opens with that line \u2014 while it is there, the server is answering from a partial parse and you are reading guesses.";
+export declare const ASK_LSP_TOOL_DESCRIPTION = "Ask the language servers \u2014 the LSP \u2014 about a symbol. If you are reaching for an LSP tool or an MCP server that wraps one, this is it: the same protocol, already running against this workspace and its open files, with no server to start. This answers questions a text search cannot, because it understands the code: it distinguishes a definition from a mention, and this class's method from another class's method of the same name.\n\nUse this before falling back to `search_codebase` for anything about a symbol. It is faster, exact, and does not need you to read files to interpret the result.\n\nReach for it the moment you are about to do one of these by hand:\n- search for a name to find where it is defined -> `definition`\n- search for a name to find what uses it, or what would break -> `references` or `callers`\n- open a file just to read a signature, type or doc comment -> `hover`\n- scroll a file, or count brackets, to work out its structure -> `document_symbols`\n- grep the repo to find which file something lives in -> `workspace_symbols`\n\nOperations:\n- `definition` \u2014 where a symbol is defined.\n- `references` \u2014 every place it is actually used.\n- `implementations` \u2014 the classes or functions implementing an interface or abstract method.\n- `type_definition` \u2014 where the type of an expression is defined.\n- `hover` \u2014 the signature, type and documentation, as an editor shows on hover.\n- `document_symbols` \u2014 an outline of one file: its classes, functions and methods.\n- `workspace_symbols` \u2014 find a symbol by name across the whole project when you do not know which file it is in.\n- `callers` \u2014 what calls this function.\n\nHow to address a symbol:\n- Usually: `path` plus `symbol` \u2014 the name as it appears in that file.\n- If you know the exact position: `path`, `line` and `character` (both 1-based).\n- If you do not know the file: `symbol` alone, with `operation: \"workspace_symbols\"`.\n\nOutput: plain text, one result per line as `file:line:column` followed by that source line, so you can go straight to the one you want rather than reading each candidate. `hover` returns the signature and documentation as text instead, and `document_symbols` and `workspace_symbols` name each symbol's kind.\n\nAn empty answer once the symbol resolved means the server understood the symbol and found nothing for it \u2014 within what it can see. It does not see uses it cannot resolve statically (`obj[name]`, a name built in a string, reflection), files it does not load, or other languages, so for `references` and `callers` above all, a text search can still find uses the server missed; run one when the answer decides an edit. `workspace_symbols` says so when it comes back empty too: it reads a project-wide index that covers the languages a server is installed for and does not index script embedded in `.html` or other template files, so nothing there is not proof of nothing anywhere. And when a JavaScript or HTML file does not parse, every answer about it opens with that line \u2014 while it is there, the server is answering from a partial parse and you are reading guesses. Other languages are not parsed here, so no such line is no promise for them.";
 /** Exported for the same reason as `CHECK_FILE_TOOL_INPUT_SCHEMA`. */
 export declare const ASK_LSP_TOOL_INPUT_SCHEMA: {
     readonly type: "object";

package/dist/extensions/tools/browser.d.ts

@@ -41,7 +41,7 @@ export declare const BROWSER_TOOL_NAME = "browser";
  * user. So the description says, in the place the model is standing when it is
  * about to ask, that the answer is available without them.
  */
-export declare const BROWSER_TOOL_DESCRIPTION = "Open a page in a real browser and report what it printed to the console and what it threw. This is how you check that a page works. Do not ask the user whether it works \u2014 open it and read the errors yourself.\n\nUse it after editing any HTML, CSS or JavaScript the page loads, and before reporting a task finished. `check_file` cannot answer this: no language server checks the script inside an `.html` file, and a file that parses can still throw the moment it runs.\n\nActions:\n- `open` \u2014 go to `url` and report the console output. Launches the browser on first use. A local file is a URL: pass the absolute path and it is converted for you.\n- `click` \u2014 click at `coordinate` (\"x,y\" in page pixels, from the screenshot).\n- `type` \u2014 type `text` at the current focus.\n- `scroll_down`, `scroll_up` \u2014 one viewport.\n- `close` \u2014 shut the browser down. Do this when finished with it.\n\nEvery action reports the console messages and uncaught errors produced while it ran, so a syntax error, a failed fetch or a null dereference comes back as text you can act on. `[error]` and `[Page Error]` lines are real failures. A page that says nothing printed nothing \u2014 that is a pass, not a failed call, and for a local file it is checked: a silent console over a file that does not parse is reported as the failure it is, not as a pass.\n\nA parse error from the browser names no line, because the script never ran. For a local file a `Delimiter scan` section follows it and names the line to edit and how many brackets that line is out by \u2014 one line per place the trouble starts, since a file can be broken in several spots at once. Fix every line it lists in one edit and reload once, rather than one edit and one reload per line. Edit those lines instead of counting brackets yourself: counting a whole file by hand costs more thinking than you have, and the scan skips strings, comments and regex literals, which counting does not.\n\nThe browser stays open between calls, so `open` once and then interact. Only one page is open at a time; `open` again to go elsewhere.";
+export declare const BROWSER_TOOL_DESCRIPTION = "Open a page in a real browser and report what it printed to the console and what it threw. This is how you check that a page works. Do not ask the user whether it works \u2014 open it and read the errors yourself.\n\nUse it after editing any HTML, CSS or JavaScript the page loads, and before reporting a task finished. `check_file` cannot answer this: no language server checks the script inside an `.html` file, and a file that parses can still throw the moment it runs.\n\nActions:\n- `open` \u2014 go to `url` and report the console output. Launches the browser on first use. A local file is a URL: pass the absolute path and it is converted for you.\n- `click` \u2014 click at `coordinate` (\"x,y\" in page pixels, from the screenshot).\n- `type` \u2014 type `text` at the current focus.\n- `scroll_down`, `scroll_up` \u2014 one viewport.\n- `close` \u2014 shut the browser down. Do this when finished with it.\n\nEvery action reports the console messages and uncaught errors produced while it ran, so a syntax error, a failed fetch or a null dereference comes back as text you can act on. `[error]` and `[Page Error]` lines are real failures. A page that says nothing printed nothing \u2014 that is a pass, not a failed call, and for a local file it is checked: the page's own scripts and the local scripts it loads by `src` are parsed, and a silent console over one that does not parse is reported as the failure it is, not as a pass. Silence says nothing threw; it does not say the page drew what it should.\n\nA parse error from the browser often names no line. For a local file the parser's own answer follows, with where it stopped, and a `Delimiter scan` section names the lines where brackets stop pairing up \u2014 one per place the trouble starts, since a file can be broken in several spots at once. Where the parser stops is where it gave up, which is not always where the mistake is, and a count says where brackets stop pairing, not which one is wrong: read the code at those lines, fix every place listed, and reload once. Do not count brackets yourself \u2014 the scan skips strings, comments and regex literals, which counting by hand does not.\n\nThe browser stays open between calls, so `open` once and then interact. Only one page is open at a time; `open` again to go elsewhere.";
 /**
  * Exported so the template generator can state this tool's real call shape.
  *

package/dist/extensions/tools/check-file.d.ts

@@ -27,6 +27,7 @@
  * therefore forces a much weaker check on the CLI than the words suggest.
  */
 import type { AgentTool } from "@cerebriline/shared";
+import { type ScriptGoal } from "./delimiter-balance";
 export declare const CHECK_FILE_TOOL_NAME = "check_file";
 /**
  * Written at the model that gets this wrong.
@@ -36,7 +37,7 @@ export declare const CHECK_FILE_TOOL_NAME = "check_file";
  * otherwise type are named here, in the description of the tool that replaces
  * them, which is where the model is standing when it is about to type one.
  */
-export declare const CHECK_FILE_TOOL_DESCRIPTION = "Check files for syntax errors and unbalanced brackets. **This is the syntax check.** Whichever word the question uses \u2014 parse error, syntax error, \"is it valid\", \"is it clean now\", \"what is still broken\" \u2014 this is the tool that answers it, for the files you name, in milliseconds, without running anything.\n\nAsk this instead of running `node --check`, `python -m py_compile`, `tsc --noEmit` or a bracket-counting script of your own. It parses the file without executing it, so it is safe on a page that would otherwise start a game or a server.\n\nWhen to call it:\n- After editing a file, to confirm the edit is valid before moving on.\n- Before reporting a task finished, on every file you changed. An edit you have not looked at is not a change you can report as done.\n- On a file you are about to change, to see what was already wrong with it.\n\nPass every file you want checked in one call.\n\nFor `.html` files each `<script>` block is parsed as JavaScript and the line numbers reported are the line numbers in the HTML file, not in the block.\n\nRead the bound carefully. This reports **syntax**, not meaning: a file that parses may still call a function that does not exist, and this will not say so. It is not a type checker, it does not run tests, and it does not know your project's lint rules \u2014 for those, use `run_commands`.\n\nOutput: JSON, in the shape a language server answers in. `files` holds one entry per path you named, each with `uri`, `checked` and `diagnostics`. There is no `success` field \u2014 diagnostics being listed is this tool working, not failing.\n\n`checked` says which check actually ran, and you have to read it before calling a file clean: `parsed` a real parser was satisfied, `delimiters` only the bracket scan reads this language so anything past brackets is unchecked, `none` nothing here reads this file type at all \u2014 empty `diagnostics` there means nothing was checked, not that the file is sound.\n\nEach diagnostic carries `range` (zero-based line and character), `severity` (1 = error) and `message`. `located: false` means the parser could not name a position, so the range is a placeholder rather than a claim about the top of the file. `complexity` appears on a file big enough to be worth a word about \u2014 a note to you, not a diagnostic.\n\nWhen a file's brackets do not match, a diagnostic names the line to edit and how many brackets that line is out by, one line per place the trouble starts \u2014 a file can be broken in several spots at once, so work through every line it lists before re-checking rather than re-checking after each one. Edit the lines it names; do not re-derive the balance by hand or with a script you write, which costs more thinking than you have and counts brackets inside strings, comments and regex literals that this scan skips. A parse error is always reported where the parser gave up, which is the closing bracket; the line named here is the one the error cannot name. The scan reads the whole file from line 1, and names each bracket by its line, its column and the text just before it: find it by that text rather than by counting columns.";
+export declare const CHECK_FILE_TOOL_DESCRIPTION = "Check files for syntax errors and unbalanced brackets. **This is the syntax check.** Whichever word the question uses \u2014 parse error, syntax error, \"is it valid\", \"is it clean now\", \"what is still broken\" \u2014 this is the tool that answers it, for the files you name, in milliseconds, without running anything.\n\nAsk this instead of running `node --check`, `python -m py_compile`, `tsc --noEmit` or a bracket-counting script of your own. It parses the file without executing it, so it is safe on a page that would otherwise start a game or a server.\n\nWhen to call it:\n- After editing a file, to confirm the edit is valid before moving on.\n- Before reporting a task finished, on every file you changed. An edit you have not looked at is not a change you can report as done.\n- On a file you are about to change, to see what was already wrong with it.\n\nPass every file you want checked in one call.\n\nFor `.html` files each `<script>` block is parsed as JavaScript and the line numbers reported are the line numbers in the HTML file, not in the block.\n\nRead the bound carefully. This reports **syntax**, not meaning: a file that parses may still call a function that does not exist, and this will not say so. It is not a type checker, it does not run tests, and it does not know your project's lint rules \u2014 for those, use `run_commands`.\n\nOutput: JSON, in the shape a language server answers in. `files` holds one entry per path you named, each with `uri`, `checked` and `diagnostics`. There is no `success` field \u2014 diagnostics being listed is this tool working, not failing.\n\n`checked` says which check actually ran, and you have to read it before calling a file clean: `parsed` a real parser was satisfied, `delimiters` only the bracket scan reads this language so anything past brackets is unchecked, `none` nothing here reads this file type at all \u2014 empty `diagnostics` there means nothing was checked, not that the file is sound.\n\nEach diagnostic carries `range` (zero-based line and character), `severity` (1 = error) and `message`. `located: false` means the parser could not name a position, so the range is a placeholder rather than a claim about the top of the file. `complexity` appears on a file big enough to be worth a word about \u2014 a note to you, not a diagnostic.\n\nA parse error is reported where the parser gave up. That is where the code stopped making sense to it, which is often but not always where the mistake is: a bracket left open earlier makes it give up later. When a file's brackets do not match, the bracket scan adds the lines where they stop pairing up and how many each line is out by, one line per place the trouble starts \u2014 read both before you edit, and work through every line listed before re-checking. A count says where brackets stop pairing, not which bracket is wrong, so read the code at those lines rather than editing them blind; do not re-derive the balance by hand or with a script of your own, which counts brackets inside strings, comments and regex literals that this scan skips. The scan names each bracket by its line, its column and the text just before it: find it by that text rather than by counting columns.";
 /**
  * The description when the host has a real checker to point at.
  *
@@ -96,12 +97,26 @@ export interface CheckFinding {
      */
     sourceText?: string;
 }
-/** Compile without running, and say what and where. */
-export declare function compileCheck(code: string, label: string, lineOffset?: number): CheckFinding | undefined;
+/**
+ * Compile without running, and say what and where.
+ *
+ * The parse the delimiter scan gates its edits on, so the two never disagree.
+ * The parse this had of its own threw nothing under Bun, which parses
+ * `vm.Script` lazily, so it never named a line there (automaticum audit
+ * 2026-11-08, B1); turned off on any line starting `import`, so a broken ES
+ * module was "No syntax errors" (B5); and refused a `#!` line and top-level
+ * `await`, which are correct (B6).
+ *
+ * `undefined` when the code parses, and equally when nothing here can tell --
+ * {@link parseVerdict} is the one that tells those apart.
+ */
+export declare function compileCheck(code: string, _label: string, lineOffset?: number, goal?: ScriptGoal): CheckFinding | undefined;
 /** A `<script>` body, and the line the body starts on. */
 export interface ScriptBlock {
     code: string;
     startLine: number;
+    /** `type="module"`: parsed by a module's rules. */
+    module?: boolean;
 }
 /**
  * The inline scripts of an HTML page.

package/dist/extensions/tools/command-guard.d.ts

@@ -12,9 +12,10 @@
  * so they cannot false-positive), split on shell separators, and the leading
  * command word of each part is compared against the lists below; output
  * redirection to files is also rejected. It will not catch every possible
- * mutation (e.g. `python -c "open(..., 'w')"` or commands hidden inside a
- * quoted `bash -c` string) — it exists to stop the common ways models edit
- * files from the shell, and entries are easy to add.
+ * mutation (e.g. `python -c "open(..., 'w')"`, or a command assembled at run
+ * time from variables) — it exists to stop the common ways models edit files
+ * from the shell, and entries are easy to add. A quoted `bash -c` / `eval`
+ * string is read as the command line it is.
  */
 import type { StructuredCommandInput } from "./schemas";
 /**

package/dist/extensions/tools/delimiter-balance.d.ts

@@ -72,6 +72,56 @@ export declare function scanDelimiters(text: string, origin?: Cursor): Delimiter
  * in code and skips every one in a string.
  */
 export declare function scanWithBalance(text: string, origin?: Cursor): DelimiterScan;
+/**
+ * Where a real parser stops on one script, in the file's own coordinates.
+ *
+ * The scan counts brackets. It cannot say which one is wrong, and an edit it
+ * worked out from the count alone was offered as checked when it fixed
+ * nothing. Measured on the manic_miner seed: line 95 holds a spare `}` that
+ * closes `class Level` early. Once line 90 was fixed the count no longer saw
+ * line 95 at all -- the class's own closing brace on line 97 was the one left
+ * over -- and the scan offered to delete that brace, with the exact editor
+ * call. The parser had stopped at line 96 the whole time, and the edit left it
+ * there. Every manic_miner gate from 2026-10-25 on was handed that edit.
+ *
+ * So no edit is offered unless the parser agrees it helped, and the line the
+ * parser stops on is named whatever the count says.
+ *
+ * `line` and `column` are absent where the runtime does not say: Bun 1.3
+ * names the line and no column, and a parse that only succeeds or fails, such
+ * as top-level `await` or JSON, names neither. On the same line without a
+ * column, an edit is offered only when the whole script parses after it.
+ */
+export interface ParseStop {
+    message: string;
+    line?: number;
+    column?: number;
+}
+/** Which grammar a span is read under. `either` is a `.js` file: a script, unless its own syntax says module. */
+export type ScriptGoal = "script" | "module" | "either";
+/**
+ * Parse one script and say where the parser stops: nothing when it parses,
+ * and null when this cannot tell.
+ *
+ * `goal` is what the span is: `script` a classic `<script>`, `module` a module
+ * script or `.mjs`, `either` a `.js` file, which is a script unless its own
+ * syntax says module. A script is parsed as a function body, so for a `.js`
+ * file a top-level `return` passes, as it does in CommonJS; a classic
+ * `<script>` is held to the stricter rule. What a real file holds and a
+ * parser here does not accept as written:
+ *
+ * - a `#!` line, which Node runs, is blanked with the line count kept;
+ * - top-level `await` in a `.js` file is parsed as an async body;
+ * - `import` or `export` in a `.js` file makes it a module, read by
+ *   {@link moduleAsScript}'s rules. In a classic `<script>` it is the error a
+ *   browser reports.
+ *
+ * `vm.compileFunction` throws on a broken body under Node and Bun alike (Bun's
+ * `vm.Script` parses lazily and throws nothing), and names the line in its
+ * stack: V8 and Bun 1.4 as `<filename>:<line>` over the source line and a
+ * caret, Bun 1.3 as `at <parse> (<filename>:<line>)`.
+ */
+export declare function findParseStop(body: string, origin?: Cursor, goal?: ScriptGoal): ParseStop | null | undefined;
 /**
  * How a prescribed repair opens, so a caller can tell a scan that names the
  * exact call from one that only names the line.

package/dist/extensions/tools/edit-verification.d.ts

@@ -73,6 +73,14 @@ export declare class EditVerificationTracker {
     private key;
     /** Whether this tracker can ever have anything to say. */
     get armed(): boolean;
+    /** Whether calls to this tool verify files. */
+    isCheckTool(toolName: string): boolean;
+    /**
+     * A checker call that returned: the files its answer reported on are
+     * checked, or every file the call named when the answer says nothing a
+     * file-by-file reading can use.
+     */
+    recordCheckResult(input: unknown, output: unknown): void;
     recordToolCall(toolName: string, input: unknown): void;
     /**
      * Files a checker reported on outside a checker call: the one a failing
@@ -99,9 +107,10 @@ export declare function isEditVerificationWrapped(tool: object): boolean;
 /**
  * Watch a tool's calls without changing what it does.
  *
- * Only the call is observed — not the result. A failed edit still counts as
- * having touched the file: the tool may have written part of it, and a guard
- * that trusted `success` would be answering a different question than "is this
- * file in a state anyone has looked at".
+ * An edit is observed at the call, not the result. A failed edit still counts
+ * as having touched the file: the tool may have written part of it, and a
+ * guard that trusted `success` would be answering a different question than
+ * "is this file in a state anyone has looked at". A check is the opposite: it
+ * counts only once it has answered, for the files the answer covers.
  */
 export declare function withEditVerificationCapture<TInput, TOutput>(tool: AgentTool<TInput, TOutput>, tracker: EditVerificationTracker): AgentTool<TInput, TOutput>;

package/dist/extensions/tools/error-locations.d.ts

@@ -2,7 +2,7 @@
  * The files a command's output blames, whatever produced the output.
  *
  * A model that runs the build gets told *that* something is broken and where
- * the tool gave up. A checker tells it *which line to edit*. Measured across
+ * the tool gave up. A checker reads the whole file and tells it where. Measured across
  * four transactions on three builds of the harness arm: the model that had the
  * first and not the second wrote its own analyser rather than asking for the
  * second — `find_error.js`, then five checkers in one transaction, then

package/dist/extensions/tools/executors/awk-parser.d.ts

@@ -104,6 +104,11 @@ export type Expr = {
 } | {
     type: "grouping";
     inner: Expr;
+}
+/** `(a, b)`: only after `print` or before `in`. */
+ | {
+    type: "exprList";
+    items: Expr[];
 };
 export type Stmt = {
     type: "print";

package/dist/extensions/tools/executors/awk.d.ts

@@ -1,8 +1,20 @@
 import type { AgentOverlay } from "../../../runtime/sandbox/overlay-fs";
 import { type Rule } from "./awk-parser";
 import { type ReadReceipts } from "./read-receipts";
-/** An awk value: a number, a string, or a string that looks like a number. */
-type Value = string | number;
+/**
+ * Input that looks like a number: a field, a `split` part, a `-v` value.
+ *
+ * awk's strnum. It tests and compares as a number and prints as it was
+ * written. A string *constant* is never one: `x = "0"` is true and
+ * `$1 == "1.0"` compares text. With the two the same, both were judged by
+ * whether the text looked numeric (automaticum audit 2026-11-08, readers 21).
+ */
+declare class StrNum {
+    readonly text: string;
+    constructor(text: string);
+}
+/** An awk value: a number, a string, or input that looks like a number. */
+type Value = string | number | StrNum;
 export declare function awkSprintf(format: string, args: Value[]): string;
 export interface RunAwkOptions {
     /** `-F`: the field separator. */

package/dist/extensions/tools/executors/bash.d.ts

@@ -148,6 +148,8 @@ export interface ShellExecutorOptions {
 export declare function createDetachedLog(retentionMs: number, marker: DetachedCommandMarker): {
     path: string;
     write(text: string): void;
+    /** Lifecycle lines -- the exit, a failure -- which the cap never drops. */
+    note(text: string): void;
     complete: () => void;
 };
 /**

package/dist/extensions/tools/executors/document/formats.d.ts

@@ -94,6 +94,8 @@ export interface DocumentReadResult {
     };
     /** Chapter titles for an ebook, in reading order. */
     contents?: string[];
+    /** Every contents entry, of which `contents` holds the first 200. */
+    contentsTotal?: number;
     /** Pages whose text is an image of text, for OCR. */
     scannedPages?: number[];
     /** Scanned pages whose text was recognized here, by `ReadOptions.recognize`. */
@@ -102,6 +104,8 @@ export interface DocumentReadResult {
     ocrLayerPages?: number[];
     /** Pages drawn as shapes: no text and no pictures to read. */
     vectorPages?: number[];
+    /** PDF pages with no text and no picture found on them. */
+    emptyPages?: number[];
     notes?: string[];
 }
 /**

package/dist/extensions/tools/executors/document/images.d.ts

@@ -22,7 +22,7 @@ export interface ExtractedImage {
     /** What the vision model saw in it, when descriptions were asked for. */
     description?: string;
     /**
-     * Set for a format no model can view (EMF, WMF, PICT, TIFF, BMP): the file is
+     * Set for a format no model can view (EMF, WMF, PICT, TIFF, BMP, JPEG 2000, …): the file is
      * kept, but it is not a picture anyone downstream can look at as it is.
      */
     notViewable?: boolean;
@@ -30,6 +30,11 @@ export interface ExtractedImage {
 }
 /** The formats a vision model is sent, which is what `inline` can attach. */
 export declare const VIEWABLE_MEDIA_TYPES: Set<string>;
+/**
+ * What to call an image's format in a sentence: the extension it was saved
+ * with, or its media type when it has none of its own.
+ */
+export declare function formatName(mediaType: string): string;
 /**
  * The media type of an image, from its first bytes.
  *

package/dist/extensions/tools/executors/document/legacy.d.ts

@@ -15,6 +15,15 @@
  * office_oxide reads whole.
  */
 import type { DocumentReadResult, ReadOptions } from "./formats";
+/**
+ * Whether a compound file is a password-protected .docx, .xlsx or .pptx.
+ *
+ * Encrypting an OOXML file wraps it in the same container as a 97-2003 one,
+ * so the bytes and often the name both say "legacy"; the old reader then
+ * reported "WordDocument stream not found" about a file that only needed its
+ * password (automaticum audit 2026-11-08, readers 28).
+ */
+export declare function isEncryptedOoxml(data: Uint8Array): Promise<boolean>;
 /** Complete PNG and JPEG images inside a compound file's streams. */
 export declare function scanCompoundImages(data: Uint8Array): Promise<Uint8Array[]>;
 export declare function readLegacyOffice(data: Uint8Array, format: "doc" | "xls" | "ppt", options: ReadOptions): Promise<DocumentReadResult>;

package/dist/extensions/tools/executors/file-read.d.ts

@@ -79,6 +79,19 @@ export interface FileReadExecutorOptions {
      */
     documentReader?: boolean;
 }
+/**
+ * How far the reader keeps counting lines after it has stopped capturing them,
+ * so that every read can report how long the file is.
+ *
+ * A ranged read used to stop at `end_line` and never learn the file's length,
+ * which left no way to ask the question at all. Measured on a 265-message
+ * session: five consecutive shell commands trying to find a line count —
+ * `wc -l` (not a Windows command), `type | find`, and three spellings of
+ * `(Get-Content).Count` — followed by two `editor` calls sending
+ * `end_line: 9999` as a guess at EOF. Counting the remaining lines costs one
+ * stream pass with no capture and no allocation.
+ */
+export declare const MAX_LINE_COUNT_SCAN = 500000;
 /** A read's text together with the line span it actually returned. */
 /**
  * Where a read's lines come from.
@@ -112,6 +125,8 @@ export interface ReadWindow {
     }[];
     /** The file holds no lines at all: seeing that is seeing all of it. */
     empty?: true;
+    /** Every line of the file is in this window. */
+    whole?: true;
 }
 /**
  * Create a file read executor using Node.js fs module

package/dist/extensions/tools/executors/read-receipts.d.ts

@@ -17,6 +17,7 @@
  * be taken must not be allowed to invent a change.
  */
 export type FileStamp = string;
+export declare const ABSENT_STAMP: FileStamp;
 export declare function readFileStamp(filePath: string): Promise<FileStamp | undefined>;
 /**
  * The stamp of a file as the caller sees it: through an agent's overlay, the
@@ -180,3 +181,12 @@ export interface OwnedReadReceipts extends ReadReceipts {
     clear(): void;
 }
 export declare function createReadReceipts(): OwnedReadReceipts;
+/**
+ * Record the lines a tool printed as read, one receipt per unbroken run.
+ *
+ * A receipt must cover an edit's whole range in one read, so runs are kept
+ * apart: lines 3 and 9 shown do not make 3-9 seen.
+ */
+export declare function creditShown(receipts: {
+    noteRead(filePath: string, first: number, last: number): void;
+} | undefined, filePath: string, lineNumbers: readonly number[]): void;

package/dist/extensions/tools/executors/search.d.ts

@@ -9,8 +9,8 @@ import type { SearchExecutor } from "../types";
  */
 export interface SearchExecutorOptions {
     /**
-     * File extensions to include in search (without dot)
-     * @default common code extensions
+     * File extensions the built-in search is limited to (without dot).
+     * @default every text file; ripgrep is never limited by this
      */
     includeExtensions?: string[];
     /**

package/dist/extensions/tools/executors/sed.d.ts

@@ -10,6 +10,26 @@ type Address = {
     regex: RegExp;
 } | {
     kind: "every";
+}
+/** `first~step`: every step-th line from first (GNU). */
+ | {
+    kind: "step";
+    first: number;
+    step: number;
+}
+/** `0` as a range start: the range is open before line 1 (GNU `0,/re/`). */
+ | {
+    kind: "zero";
+}
+/** `+N` as a range end: N lines after the line that opened it (GNU). */
+ | {
+    kind: "relative";
+    count: number;
+}
+/** `~N` as a range end: up to the next line that is a multiple of N (GNU). */
+ | {
+    kind: "multiple";
+    of: number;
 };
 interface Command {
     start?: Address;
@@ -32,6 +52,10 @@ interface Command {
     text?: string;
     /** Range state while executing. */
     active?: boolean;
+    /** For a range whose end is a line count: the line it closes on. */
+    closesAt?: number;
+    /** Set by `selects`: this line is the last one of the command's range. */
+    closing?: boolean;
 }
 /**
  * Parse a sed script into commands.
@@ -45,6 +69,22 @@ export interface RunSedResult {
     output: string;
     /** Whether any command changed the text. */
     changed: boolean;
+    /**
+     * Whether any command selected a line and acted on it: an `s` that matched
+     * but wrote the same text back matched something, and "matched nothing"
+     * was a false account of it.
+     */
+    matched: boolean;
+    /**
+     * Input lines whose text reached the output, in order and once each: what
+     * a read-only run showed, and so what it may credit as read.
+     */
+    shown: number[];
+    /**
+     * Input lines the script changed: rewritten, deleted, replaced, or with
+     * text put before or after them. What an in-place run must have seen.
+     */
+    touched: number[];
 }
 /** Run a parsed script over text. Pure: no filesystem, so it is easy to test. */
 export declare function runSedScript(input: string, commands: Command[], quiet?: boolean): RunSedResult;

package/dist/extensions/tools/executors/unchanged-reads.d.ts

@@ -36,6 +36,12 @@ export interface ReadKeyParts {
     firstLine: number;
     lastLine: number;
     withLineNumbers: boolean;
+    /**
+     * The window was the whole file. Otherwise the comparison says nothing
+     * about the lines outside it, and "has not changed" claimed it did
+     * (automaticum audit 2026-11-08, readers 15).
+     */
+    wholeFile?: boolean;
 }
 export interface ReadLedger {
     /**

package/dist/extensions/tools/executors/web-fetch.d.ts

@@ -38,6 +38,18 @@ export interface WebFetchExecutorOptions {
      */
     maxRedirects?: number;
 }
+/**
+ * Decode character references in one pass, so `<` is the text
+ * `&lt;` -- decoded entity by entity it became `<`, and `&#x27;` or an emoji
+ * above U+FFFF was not decoded at all (automaticum audit 2026-11-08,
+ * readers 28).
+ */
+export declare function decodeEntities(text: string): string;
+/**
+ * Extract text content from HTML: tags stripped, block elements as line
+ * breaks, `<pre>` kept as written, entities decoded once.
+ */
+export declare function htmlToText(html: string): string;
 /**
  * Create a web fetch executor using native fetch
  *

package/dist/extensions/tools/executors/whole-file.d.ts

@@ -15,11 +15,16 @@ export declare const MAX_TEXT_STREAM_BYTES = 100000000;
 export declare const BINARY_SNIFF_BYTES = 8000;
 /** Why a file is not read whole: too large, or not text. */
 export interface WholeFileRefusal {
-    kind: "size" | "binary";
+    kind: "size" | "binary" | "utf16";
     message: string;
 }
 /**
  * Why `filePath` must not be read whole, or nothing when it may. A path that
  * cannot be opened is left to the caller's own read, which says why.
  */
-export declare function wholeFileRefusal(filePath: string, tool: string): Promise<WholeFileRefusal | undefined>;
+export declare function wholeFileRefusal(filePath: string, tool: string, 
+/** How the refusal opens: what did not happen to the file. */
+outcome?: string): Promise<WholeFileRefusal | undefined>;
+/** The UTF-16 byte order a file's byte-order mark names, if it has one. */
+export declare function utf16ByteOrder(head: Uint8Array): "utf-16le" | "utf-16be" | undefined;
+export declare function readHead(filePath: string, bytes: number): Promise<Uint8Array>;

package/dist/extensions/tools/helpers.d.ts

@@ -9,9 +9,23 @@ export declare function getEditorSizeError(input: EditFileInput): string | null;
  */
 export declare class TimeoutError extends Error {
     readonly timeoutMs: number;
-    constructor(message: string, timeoutMs: number);
+    /**
+     * What the work printed before it was stopped, when there is any. A
+     * timeout dropped it: the test runner's FAIL line printed before it hung
+     * was exactly what the model needed (automaticum audit 2026-11-08,
+     * readers 8).
+     */
+    readonly output?: string;
+    constructor(message: string, timeoutMs: number, output?: string);
 }
 export declare function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T>;
+/**
+ * What a writing tool's timeout means: the call was abandoned, not stopped,
+ * so the files may hold some or all of its changes. "Failed" read as
+ * "nothing happened", and the model ran the same edit again over a file
+ * that already had it (automaticum audit 2026-11-08, outside scope).
+ */
+export declare function abandonedWriteMessage(tool: string, timeoutMs: number): string;
 export declare function formatReadFileQuery(request: ReadFileRequest): string;
 export declare function getReadFileRangeError(request: ReadFileRequest): string | null;
 /**

package/dist/extensions/tools/jev.d.ts

@@ -196,7 +196,7 @@ export declare function listJevModels(endpoint: Pick<JevEndpoint, "apiKey" | "ba
 export declare function jevConfidence(answer: JevAnswer): number;
 /** Cut a state part to its ceiling, keeping the head and the tail. */
 export declare function boundJevText(text: string, max?: number): string;
-export declare const JEV_TOOL_DESCRIPTION = "Get a calibrated confidence score from Jev, an external scoring model, before acting on something you are not sure of. Jev reads the context you give it and answers typed questions with probabilities; it writes no text and cannot explain itself.\n\nUse it when you are unsure:\n- whether you understood the user's request \u2014 ask whether the request is ambiguous, or which of your readings it means;\n- whether a fact your answer rests on is supported by what you have read \u2014 put the source text in the context and ask whether it states the claim;\n- which approach, option or file to choose;\n- how complex the task is, before deciding to escalate or delegate it.\n\nArguments:\n- `context` \u2014 the situation, in plain text: what the user asked, what you found, what you are deciding. Only what the questions need; unrelated text makes the answers worse.\n- `questions` \u2014 1 to 10, all asked in one call. Each has an `id`, a `kind` and a `question`:\n  - `yes_no` \u2014 a yes/no question. Returns the probability of yes.\n  - `choice` \u2014 pick one of `options` (2 to 50). Include a \"none of these\" option when that is possible: a choice always picks something.\n  - `score` \u2014 rate on `levels` (2 to 10, lowest first).\n  Set `high_stakes: true` on a question whose wrong answer is costly; it must clear a higher bar.\n\nEach answer comes back as confident or unsure against the user's confidence floor. Act on a confident answer. On an unsure one, verify it yourself or ask the user \u2014 do not treat it as settled. Jev is weak at arithmetic, counting and multi-step reasoning, so check those in code, and ask one property per question rather than one broad question.";
+export declare const JEV_TOOL_DESCRIPTION: string;
 export declare const JEV_TOOL_INPUT_SCHEMA: {
     readonly type: "object";
     readonly properties: {