aegis-desktop 1.0.10 → 1.0.13

package/lib/local/engine.js

@@ -167,6 +167,32 @@ function normalizeToolArgs(T, name, args, ctx) {
   return fn(name, args, ctx);
 }
 
+/**
+ * Is `dir` inside a git work tree? Walks up the way git itself does, so a turn
+ * running in a subdirectory of a repo is still told it is one.
+ *
+ * Returns `'git'`, `''` (definitely not a repo), or `null` when the probe could
+ * not answer — the caller omits the line rather than asserting "not a repo",
+ * because a wrong negative is exactly the kind of fact a model will act on.
+ */
+function detectVcs(dir) {
+  if (!dir) return null;
+  try {
+    const fs = require('node:fs');
+    const path = require('node:path');
+    let probe = path.resolve(String(dir));
+    for (let i = 0; i < 8; i += 1) {
+      if (fs.existsSync(path.join(probe, '.git'))) return 'git';
+      const up = path.dirname(probe);
+      if (up === probe) break;
+      probe = up;
+    }
+    return '';
+  } catch {
+    return null;
+  }
+}
+
 function hostEnv(base = {}, supplied = {}, payload = null) {
   const b = base || {};
   const s = supplied || {};
@@ -250,6 +276,16 @@ function hostEnv(base = {}, supplied = {}, payload = null) {
     // a `{ key, value }` facet, or a bare string.
     languages: pick('languages', b.languages),
     cwd: pick('cwd', cwd),
+    // Whether the turn's directory is a git work tree, probed once per turn.
+    // Measured reason: the work rules order the model to check prior work with
+    // `git log` before it starts, and a benchmark workspace (a temp dir holding
+    // three files) is NOT a repo. On every task the model dutifully spent its
+    // second round on `cd … && git log`, paid a failed exec, and carried the
+    // error text into every later round's prompt — one wasted round in seven,
+    // and a bigger prefix for the rest. The host already knew; this states it
+    // so the rule can say "skip the sources the workspace does not have" and
+    // mean something the model can act on without guessing.
+    vcs: pick('vcs', b.vcs != null ? b.vcs : detectVcs(cwd)),
     shell: pick('shell', shellName),
     shellKind: pick('shellKind', shellKind),
     roots: pick('roots', b.roots),
@@ -524,27 +560,43 @@ const EFFORT_TOKEN_BUDGET = { low: 8192, medium: 16384, high: 32768 };
 /**
  * DeepSeek native reasoning level per config rung.
  *
- * The field is `reasoning_effort`, NOT `effort`. Verified live 2026-10-02: a
- * DeepSeek body carrying `effort` returns HTTP 200 and is ignored, while
- * `reasoning_effort` binds and rejects an unknown value with a 422 naming its
- * enum (none|minimal|low|medium|high|xhigh|ultra|max). Behaviourally,
- * `reasoning_effort:"none"` produced 0 reasoning_content chars and `"max"`
- * produced 138, whereas `effort:"none"` still produced 112 — thinking stayed
- * on. So the old field was inert on every turn, and inertness is the worst
- * failure here: it 200s, nothing surfaces, and the model merely thinks at the
- * wrong depth.
+ * The field is `effort`, NOT `reasoning_effort`. Verified live 2026-10-21
+ * against the surface this client actually reaches — the relay's
+ * `https://api.deepseek.com/anthropic` transport — by measuring output tokens
+ * over interleaved paired samples (n=12) against an absent-field baseline:
+ *
+ *   absent 818 · low 772 · medium 836 · high 818 · max 1494
+ *
+ * Only `max` separates from sending nothing. `GET /models` reports
+ * `supported_levels: ["low","high","max"]`, default `high`, on both live ids
+ * (`deepseek-flash`, `deepseek-v4-pro`) — so `medium` is not a level these
+ * models have. It passes the deserializer (unknown values *do* 422 with the
+ * enum, so validation is real) and is then absorbed into the default, which is
+ * this codebase's worst failure mode: a 200, nothing surfaced, and the model
+ * thinking at a depth nobody chose.
+ *
+ * What the earlier version of this comment asserted — that `reasoning_effort`
+ * binds and `effort` is ignored — was measured on the vendor's OpenAI-shaped
+ * `/chat/completions`, a surface this client never reaches, and it led to the
+ * knob being dead end-to-end: aegis1 forwards `reasoning_effort` only for
+ * BYOK_REASONING_EFFORT_PROVIDERS (openai/groq/gemini/grok — deepseek is
+ * absent), so the field was dropped at the relay. The `effort` channel is the
+ * one aegis1 gates on `provider_id == "deepseek"` (app.py) and that the
+ * Anthropic adapter nests as `output_config.effort`; it is the only channel
+ * that reaches the vendor, and the only one that measurably binds.
  *
- * Every rung of the knob has a namesake in that enum, so the map is 1:1 rather
- * than the earlier (low|max, no medium) fold, which rested on the mistaken
- * belief that DeepSeek had no `medium`. `max_tokens` (EFFORT_TOKEN_BUDGET)
- * still scales as the output ceiling, since hidden chain-of-thought shares that
- * budget on DeepSeek.
+ * The map folds `medium` upward for the same reason the Gemini row does: the
+ * vendor has no such level, and a rung that 200s while doing nothing is worse
+ * than one that says what it does. `max` is deliberately NOT reachable — it is
+ * not a rung of this knob, and mapping the default rung onto it would silently
+ * multiply reasoning spend on every turn nobody asked to deepen.
+ * `max_tokens` (EFFORT_TOKEN_BUDGET) still scales as the output ceiling, since
+ * hidden chain-of-thought shares that budget on DeepSeek.
  *
- * Mirrors the upstream engine's src/backend.js DEEPSEEK_EFFORT verbatim;
- * desktop/renderer/budget.js carries the renderer's copy for the same
- * no-drift guarantee as DEEPSEEK_REASONING_MODEL_RE above.
+ * desktop/renderer/budget.js carries the renderer's copy; test/budget.test.mjs
+ * compares the two tables, so the mirror cannot drift silently.
  */
-const DEEPSEEK_EFFORT = { low: 'low', medium: 'medium', high: 'high' };
+const DEEPSEEK_EFFORT = { low: 'low', medium: 'high', high: 'high' };
 
 /**
  * Per-family effort translation, mirroring the upstream engine's
@@ -565,7 +617,7 @@ const DEEPSEEK_EFFORT = { low: 'low', medium: 'medium', high: 'high' };
 const EFFORT_IDENTITY = { low: 'low', medium: 'medium', high: 'high' };
 const EFFORT_INERT_RE = /non-reasoning/i;
 const EFFORT_DIALECTS = [
-  { provider: 'deepseek', re: DEEPSEEK_REASONING_MODEL_RE, field: 'reasoning_effort', map: DEEPSEEK_EFFORT },
+  { provider: 'deepseek', re: DEEPSEEK_REASONING_MODEL_RE, field: 'effort', map: DEEPSEEK_EFFORT },
   { provider: 'openai', re: /^(gpt-5|o[0-9])/i, field: 'reasoning_effort', map: EFFORT_IDENTITY },
   { provider: 'groq', re: /^(openai\/gpt-oss|qwen\/qwen3)/i, field: 'reasoning_effort', map: EFFORT_IDENTITY },
   { provider: 'xai', re: /^grok-(4\.[5-9]|[5-9])/, field: 'reasoning_effort', map: EFFORT_IDENTITY },
@@ -1967,8 +2019,8 @@ function createLocalEngine({
       const { provider, model: bareModel } = splitByokModel(opts.model);
       // Translate the rung for THIS vendor once, and carry the verdict rather
       // than a bare level: the relay validates strictly upstream and the field
-      // name is not portable (DeepSeek's OpenAI-compatible surface takes
-      // `reasoning_effort`, same spelling as OpenAI's). Undefined for a family
+      // name is not portable (DeepSeek's `/anthropic` transport takes `effort`,
+      // OpenAI-shaped vendors take `reasoning_effort`). Undefined for a family
       // with no dialect, which the transport then omits entirely.
       const effort = nativeEffort(provider, bareModel, opts.effort);
       try {
@@ -1999,10 +2051,16 @@ function createLocalEngine({
           toolChoice: opts.toolChoice,
           // Native effort knob, field and level both from the dialect table.
           // `bareModel` is already provider-less, so it matches the dialect
-          // regexes without further stripping. Only a dialect whose field is
-          // `reasoning_effort` is forwarded: DeepSeek used to ride a separate
-          // `effort` body key, which the API 200s and ignores, so that whole
-          // second channel is gone rather than left as a way to reintroduce it.
+          // regexes without further stripping. Both wire channels are live, and
+          // which one is used is the dialect's decision, not this call site's:
+          // DeepSeek's `/anthropic` transport takes `effort` (aegis1 gates it on
+          // provider_id == "deepseek" and the adapter nests it as
+          // `output_config.effort`), while the OpenAI-shaped vendors take
+          // `reasoning_effort`. Routing on the field name is what keeps a
+          // dialect from being silently dropped here — the previous form
+          // forwarded only `reasoning_effort`, so turning DeepSeek's dialect
+          // over to `effort` would have died at this line.
+          effort: effort && effort.field === 'effort' ? effort.level : undefined,
           reasoningEffort: effort && effort.field === 'reasoning_effort' ? effort.level : undefined,
           stream: true,
           onStream: opts.onDelta,
@@ -2541,7 +2599,34 @@ function createLocalEngine({
       // dispatch is summed, including the truncation retry and the synthesis
       // re-dispatch: both are real, separately billed provider calls.
       const turnUsage = { calls: 0 };
-      const USAGE_FIELDS = ['input_tokens', 'output_tokens', 'prompt_tokens', 'completion_tokens', 'total_tokens'];
+      // The cache fields MUST be listed here, not just summed at the top level.
+      // DeepSeek reports its hit count as `prompt_cache_hit_tokens` and its
+      // miss count as `prompt_cache_miss_tokens`, and neither name was in this
+      // list — so every tool-using turn dropped them on the way out and handed
+      // its caller a usage object with no cache information at all. The CLI's
+      // `--json` republishes exactly this accumulator, `usageBuckets` then had
+      // nothing to read, and the published cost of an agentic run was priced
+      // entirely at the miss rate. Measured on the 3-task sweep: `cache_read: 0`
+      // on all three trials (tokens_in 210,904) while the row's own baseline
+      // showed 72,448 cached tokens. The same defect the CLI's per-turn readout
+      // was fixed for, here one layer below it.
+      const USAGE_FIELDS = [
+        'input_tokens', 'output_tokens', 'prompt_tokens', 'completion_tokens', 'total_tokens',
+        // Anthropic spelling (disjoint from its input count).
+        'cache_read_input_tokens', 'cache_creation_input_tokens',
+        // DeepSeek/OpenAI spelling (both SUBSETs of the prompt count, which is
+        // what `usageBuckets` detects and subtracts rather than double-billing).
+        'prompt_cache_hit_tokens', 'prompt_cache_miss_tokens',
+        // Hidden deliberation, which every provider here bills as OUTPUT but
+        // none of them split out for free. These were absent from the list
+        // while `reasoningTokensOf` (below) already knew how to read them, so
+        // the one place that could have separated "wrote more code" from
+        // "thought longer" threw the split away at the accumulator and handed
+        // its caller a single `output_tokens` with CoT folded in. A benchmark
+        // row could therefore see that a turn cost 1.9x another's output and
+        // still have no way to say which half moved.
+        'reasoning_tokens', 'thinking_tokens',
+      ];
       const addUsage = (res) => {
         const u = res && res.usage;
         if (!u || typeof u !== 'object') return;

package/lib/local/prompt.js

@@ -30,50 +30,62 @@
 
 /** Identity + work rules. Ported from the upstream engine reference. */
 const MAIN_CHAT_PROMPT =
-  `You are Aegiscodex, a terminal coding assistant that works in the user's repository. ` +
-  `Help with software engineering tasks: read and reason about code, write and edit files, ` +
-  `run shell commands, and investigate bugs. Work rules:\n` +
+  `You are Aegiscodex, a terminal coding assistant working in the user's repository: read and ` +
+  `reason about code, write and edit files, run shell commands, investigate bugs. Work rules:\n` +
+  `- Output is billed by the token and is the largest line on the bill, so spend it where it is ` +
+  `  read. Before a tool call, one short sentence on what you are about to find out. Do NOT ` +
+  `  restate file contents, diffs, command output or test results the user can already see. ` +
+  `  Finish with the answer in a few lines — expand only when asked to explain, or when the ` +
+  `  change's correctness depends on a detail the user must check.\n` +
+  `- Batch independent tool calls into ONE turn: read several files, or grep for several ` +
+  `  patterns, at once, or use one exec command that does the whole job. Every round ` +
+  `  re-sends the prefix and bills fresh output; one call per round is the expensive shape.\n` +
   `- Use tools silently. A one-line reason is enough; do not narrate your plan as a story. ` +
   `- Never claim what a tool found or what a command returned before the tool actually runs. ` +
   `  Report only the results you really received. ` +
-  `- Before you start a fix or feature the user asks for, check whether they have asked for ` +
-  `  it before and whether it was already delivered: look in recalled memory, ` +
-  `  ~/.aegiscode/queue.jsonl, PLAN.md/notes, and \`git log\` for the same demand. If it was ` +
-  `  resolved before and the problem is back, report how it was resolved (the commit, file, or ` +
-  `  mechanism that fixed it) and why it regressed, then fix the cause — never re-fix blind as ` +
-  `  if the request were new. If it was never met, say so plainly before starting. ` +
-  `- Match the response to the request. A greeting, a question about something you already ` +
-  `  know, or a request for an opinion is answered in plain words with NO tools. Only reach ` +
-  `  for a tool when the answer genuinely depends on something in this repo or on this ` +
-  `  machine. "hey" is not a task.\n` +
+  `- Before starting a fix or feature, check whether they have asked for it before and whether ` +
+  `  it was delivered: recalled memory, \`queue.jsonl\`, \`PLAN.md\`/notes and \`git log\` — ` +
+  `  ONE batched command over sources that exist: if the Environment block says this ` +
+  `  directory has no version control, skip it. ` +
+  `  If it was resolved before and the problem is back, report how it was resolved and ` +
+  `  why it regressed, then fix the cause — never re-fix blind as if it were new. ` +
+  `  If it was never met, say so plainly before starting. ` +
+  `- Match the response to the request. A greeting, a question you already know the answer to, ` +
+  `  or a request for an opinion is answered in plain words with NO tools. Reach for a tool ` +
+  `  only when the answer depends on something in this repo or on this machine. ` +
+  `  "hey" is not a task.\n` +
   `- WHEN THE USER HAS ASKED FOR WORK: act, don't just inspect. After at most 2 rounds of ` +
   `  reading or exploration, start making changes with writeFile or editFile. Reconnaissance ` +
-  `  is not progress — implement, then verify. This rule is about HOW to carry out a task you ` +
-  `  were given; it is never a reason to invent one. Never write or modify a file the user ` +
+  `  is not progress — implement, then verify. This is about HOW to carry out a task you were ` +
+  `  given; it is never a reason to invent one. Never write or modify a file the user ` +
   `  did not ask you to touch.\n` +
-  `- Zero tolerance for stalling: once the target file/cause is identified and only the edit ` +
-  `  remains, make it in the same turn. Never end a turn with an empty or no-op response, or a ` +
-  `  "let me continue"/"I'll now…" placeholder when the user says continue — that is not an ` +
-  `  answer and it wastes their turn. This has been flagged as non-compliance before; treat it ` +
-  `  as a hard rule. ` +
-  `- When you have what you need, stop using tools and give a concise, direct answer to the ` +
-  `  user's question. Never end your turn with an intention like "Let me check…" or "I'll now…" ` +
-  `  — that is not an answer. ` +
+  `- Zero tolerance for stalling: once the cause is identified and only the edit remains, make ` +
+  `  it in the same turn. Never end a turn with an empty or no-op response, or a "let me ` +
+  `  continue"/"I'll now…" placeholder when the user says continue — that wastes their turn. ` +
+  `  This has been flagged as non-compliance before; treat it as a hard rule. ` +
+  `- When you have what you need, stop using tools and give a concise, direct answer. Never ` +
+  `  end a turn with an intention like "Let me check…" — that is not an answer. ` +
   `- When a focused multi-step sub-task can be delegated, use the task tool to spawn a ` +
-  `  specialist subagent rather than doing everything inline. ` +
+  `  specialist subagent rather than doing it inline. ` +
   `- If the user references a workflow you don't recognize, inspect the repo/scripts for that ` +
-  `  mechanism before acting — don't assume it means inline work.`;
+  `  mechanism before acting.`;
 
-/** The tools the desktop actually advertises (kept in step with tools.js). */
+/**
+ * The tool line: what each tool is, and the two facts a schema cannot carry.
+ *
+ * It used to restate the path rule in full — absolute, `~` expansion, relative
+ * resolution — which `PATH_ARG_DESC` already says once per path argument in nine
+ * schemas. That duplication is what `d01068b` unwound from the schemas; this is
+ * the other end of it. What stays is the part no schema carries: the
+ * platform-specific example (the one form a model gets wrong) and the persistent
+ * shell, which is a property of the session rather than an argument.
+ */
 const TOOL_LINE =
-  'Tools: readFile, writeFile, editFile, listDir, glob, grep, exec, task. Paths are absolute and ' +
-  'must be written in the form THIS machine uses — read the platform and home directory in the ' +
-  'Environment block below and use them: on win32 that means C:\\Users\\you\\Desktop\\file.txt, ' +
-  'not /home/you/Desktop/file.txt or /tmp/file.txt. "~" and "~/…" mean the home directory and are ' +
-  'expanded for you; a relative path resolves against the working directory. ' +
-  'exec runs in a persistent shell session on this machine — cd and exported env vars carry ' +
-  'across calls within the turn, like a real terminal. task spawns a specialist subagent ' +
-  '(its own tool loop, same model) for a focused, self-contained piece of work.';
+  'Tools: readFile, writeFile, editFile, listDir, glob, grep, exec, task. Paths are absolute ' +
+  'in the form THIS machine uses (see the Environment block): on win32 that means ' +
+  'C:\\Users\\you\\Desktop\\file.txt, not /home/you/Desktop/file.txt or /tmp/file.txt. ' +
+  'exec runs in a persistent shell session — cd and exported env vars carry across calls ' +
+  'within the turn. task spawns a specialist subagent (its own tool loop, same model).';
 
 /**
  * One durable-language entry as a sentence fragment, accepting the three shapes
@@ -109,6 +121,7 @@ function environmentPreamble(env = {}) {
     localeName,
     languages,
     cwd,
+    vcs,
     shell,
     shellKind,
     roots,
@@ -164,8 +177,7 @@ function environmentPreamble(env = {}) {
   if (desktopdir) {
     bits.push(
       `desktop directory: ${desktopdir} — use this exact path when the user says "my desktop"; ` +
-        'do NOT build it yourself from the home directory, because it is not always a folder ' +
-        'called "Desktop" there',
+        'do NOT build it yourself from the home directory',
     );
   }
   // Same failure mode as the desktop line, one directory over, and reported
@@ -176,13 +188,31 @@ function environmentPreamble(env = {}) {
   // missing path cannot tell a typo from an empty directory.
   if (dataDir) {
     bits.push(
-      `AEGIS data directory: ${dataDir} — this is the store itself (config, sessions, ` +
+      `AEGIS data directory: ${dataDir} — the store itself (config, sessions, ` +
         'credentials, queue). Use this exact path; do NOT append it to the home directory ' +
         'yourself, because a dropped separator ("C:\\Users\\you.aegiscode") names a path that ' +
         'does not exist and looks like an empty directory rather than a mistake',
     );
   }
   if (cwd) bits.push(`working directory: ${cwd}`);
+  // The version-control fact, which turns the work rules' "check whether this
+  // was already delivered" from a guess into a decision. Measured: in a temp
+  // workspace with no `.git`, the model still ran `git log` on its second round
+  // of all three tasks, spent a round on a guaranteed failure, and carried the
+  // error into the rest of the turn. Stated only when the host actually probed
+  // (`null`/`undefined` means "could not tell", and silence beats a wrong fact).
+  if (vcs === 'git') {
+    bits.push(
+      `version control: this directory IS inside a git work tree, so \`git log\`, ` +
+        '`git diff` and `git status` are usable for checking what was already done',
+    );
+  } else if (vcs === '') {
+    bits.push(
+      `version control: this directory is NOT a git repository and has no history to ` +
+        'consult — do NOT run `git log`, `git diff`, `git blame` or `git status`; they ' +
+        'fail here and cost a round. Read the files that exist instead',
+    );
+  }
   if (shell) bits.push(`exec shell: ${shell}${shellKind ? ` (${shellKind})` : ''}`);
   if (model) bits.push(`model: ${model}`);
   if (appVersion) bits.push(`AEGIS Desktop ${appVersion}`);

package/lib/local/tools.js

@@ -86,10 +86,18 @@ const OUTPUT_CAP = 30_000; // chars fed back to the model per tool result
  * Desktop. The schema is the first place to say so — a refusal after the fact
  * costs the model a round, a correct description costs it nothing.
  */
+// Kept SHORT on purpose. This sentence is repeated in the description of every
+// path argument (9 of the 10 tools), so its length is paid once per tool, every
+// round, and the tool schemas are part of the wire prefix the provider is asked
+// to cache. The long form spelled out win32 examples and the Environment-block
+// cross-reference — 267 chars, ~68 tokens, ~616 tokens per round once
+// multiplied across the nine. That instruction is NOT lost: prompt.js's
+// TOOL_LINE states the same rule once, in the system prompt where it belongs
+// and where it costs one copy instead of nine. `test/tool-paths.test.mjs`
+// asserts this constant appears in each path argument, so it must stay the
+// single shared string rather than being inlined per tool.
 const PATH_ARG_DESC =
-  'Absolute path in THIS machine\'s own form (the Environment block names the platform and home ' +
-  'directory — a win32 host needs C:\\Users\\you\\file.txt, never /home/you/file.txt), or "~" / ' +
-  '"~/…" for the home directory. A relative path resolves against the working directory.';
+  'Absolute path on THIS machine; "~"/"~/…" = home. Relative resolves against the working directory.';
 
 /** `<what>. <the path rules>` — the shape every path argument's description takes. */
 const pathDesc = (what) => `${what}. ${PATH_ARG_DESC}`;
@@ -297,18 +305,45 @@ const SCHEMAS = {
 // MAX_SUBAGENT_DEPTH, hard-bounding runaway recursion.
 const SUBAGENT_TOOL = 'task';
 
+/**
+ * The hook layer (`hooks`, `installHooks`) is the ONE part of this registry that
+ * is not agent work, and it is the one part the benchmark never touches.
+ *
+ * Measured on `benchmarks/raw/beat-pi-20261022-2318` (three tasks, the same wire
+ * model, nine trials): the advertised schemas are re-sent as a wire PREFIX on
+ * every round, and these two are 427 of its ~1,757 tokens. On the round that
+ * misses the prefix cache they are billed at the miss rate; on every later round
+ * they are billed at the cheap hit rate but are still tokens the model reads
+ * before it reads the task. Pi ships seven tools and no hook surface at all.
+ *
+ * So they stay RUNNABLE (`isTool`, `executeTool`, `toolList`, the CLI's `/hooks`)
+ * and stay on the schema list for a caller that asks for them, but they are no
+ * longer advertised to the model by default. Capability is unchanged; the
+ * prefix it was paying for is gone.
+ */
+const HOOK_TOOLS = new Set(['hooks', 'installHooks']);
+
 /** Tool names in advertisement order. `includeSubagent: false` drops task (depth cap). */
-function toolNames({ includeSubagent = true } = {}) {
-  return schemaList(includeSubagent).map((s) => s.name);
+function toolNames({ includeSubagent = true, includeHooks = false } = {}) {
+  return schemaList({ includeSubagent, includeHooks }).map((s) => s.name);
 }
 
-function schemaList(includeSubagent) {
-  return Object.values(SCHEMAS).filter((s) => includeSubagent || s.name !== SUBAGENT_TOOL);
+function schemaList({ includeSubagent = true, includeHooks = false } = {}) {
+  return Object.values(SCHEMAS).filter(
+    (s) =>
+      (includeSubagent || s.name !== SUBAGENT_TOOL) &&
+      (includeHooks || !HOOK_TOOLS.has(s.name))
+  );
 }
 
-/** OpenAI-compatible /chat/completions tool definitions ({type:'function', function}). */
-function openaiTools({ includeSubagent = true } = {}) {
-  return schemaList(includeSubagent).map((s) => ({
+/**
+ * OpenAI-compatible /chat/completions tool definitions ({type:'function', function}).
+ * `includeHooks: true` re-advertises the hook tools; the default is the agent
+ * set, because a hook install is a thing the USER asks the CLI for, not a step
+ * in a coding task.
+ */
+function openaiTools({ includeSubagent = true, includeHooks = false } = {}) {
+  return schemaList({ includeSubagent, includeHooks }).map((s) => ({
     type: 'function',
     function: { name: s.name, description: s.description, parameters: s.parameters },
   }));
@@ -319,10 +354,10 @@ function openaiTools({ includeSubagent = true } = {}) {
  * goes through the AEGIS relay, which speaks the OpenAI shape — so this takes
  * no `wire` argument. The Anthropic-shaped variant went away with the
  * direct-dial transport. `includeSubagent: false` drops the task tool
- * (subagent depth cap).
+ * (subagent depth cap); `includeHooks: true` re-adds hooks/installHooks.
  */
-function toolsFor({ includeSubagent = true } = {}) {
-  return openaiTools({ includeSubagent });
+function toolsFor({ includeSubagent = true, includeHooks = false } = {}) {
+  return openaiTools({ includeSubagent, includeHooks });
 }
 
 // ── Path normalisation ──────────────────────────────────────────────────────
@@ -1175,6 +1210,7 @@ module.exports = {
   // schemas
   SCHEMAS,
   SUBAGENT_TOOL,
+  HOOK_TOOLS,
   toolNames,
   openaiTools,
   toolsFor,

package/lib/settings.js

@@ -103,6 +103,19 @@ const QUICK_LAUNCHER_NAMESPACE = '__quickLauncher';
  *  fighting existing app/OS bindings, memorable enough to type once. */
 const DEFAULT_QUICK_LAUNCHER_SHORTCUT = 'CmdOrCtrl+Shift+Space';
 
+/** Reserved namespace for where `fingerprint publish`/the vault card sends
+ *  sealed records: `{ backend }`, one of VAULT_BACKEND_VALUES — app-level, not
+ *  a provider, for the same reason the quick launcher isn't. Default is
+ *  `aegiscloud` (unset reads as the default, same convention as confirm mode)
+ *  because it is the only backend that exists on a fresh install — see
+ *  client/record-vault.js's own DEFAULT_BACKEND. `drive` asks the fingerprint
+ *  service to talk to rclone's `gdrive` remote instead (the user's own Drive,
+ *  configured by them); `off` means publish/anchor/vault/audit refuse with a
+ *  named reason rather than silently reaching either backend. */
+const VAULT_BACKEND_NAMESPACE = '__vaultBackend';
+const DEFAULT_VAULT_BACKEND = 'aegiscloud';
+const VAULT_BACKEND_VALUES = Object.freeze(['aegiscloud', 'drive', 'off']);
+
 /** Reserved namespace for the tool-call approval ("confirm mode") preference:
  *  `{ enabled }` — app-level, not a provider, so it stays out of the provider
  *  CRUD surface for the same reason the AEGIS key does. Default is ON
@@ -138,31 +151,34 @@ const AVATAR_NAMESPACE = '__avatar';
  *  main.js telemetryEnabled() through getTelemetryOptIn(). */
 const TELEMETRY_NAMESPACE = '__telemetry';
 
-/** Reserved namespace for the auto-drain opt-in:
+/** Reserved namespace for the auto-drain switch:
  *  `{ enabled, intervalMs }` — app-level, not a provider.
  *
- *  DEFAULT OFF, and unlike every preference above that default is the design
- *  rather than a convention: this is the one setting in the app that causes a
- *  full tool loop to run on a real model in the user's checkout with nobody
- *  watching. desktop/main.js and desktop/preload.js both used to state the
- *  absolute rule — "there is no interval, no drain at startup, and no
- *  drain-on-idle anywhere" — and that rule is still what an install that never
- *  touches this namespace gets. What changed (user request, phase A of the
- *  automation work) is that the rule became a DEFAULT instead of an absolute:
- *  an explicit `enabled: true` here is the only thing that arms a timer, the
- *  toggle that writes it is in the queue card, and `lib/auto.js` refuses to
- *  run a tick when the queue is empty or another host already holds the drain
- *  lock. Nothing secret lives here, so no encryption — same shape as
- *  `__confirmMode`/`__memoryPersist` above. */
+ *  DEFAULT ON (user request: the queue must work with no click and nothing on
+ *  screen). An absent namespace means "drain in the background"; only an
+ *  explicit `enabled: false` disarms it, and that is what the settings store
+ *  writes when someone turns the worker off from the CLI or by hand.
+ *
+ *  The guards are what make that default defensible, and they live in
+ *  `lib/auto.js`, not here: a tick skips when the queue is empty (so an idle
+ *  install costs one JSON parse and no lock I/O), when another host holds the
+ *  drain lock, when a drain is already in flight, and when the switch was
+ *  turned off since the last tick — the switch is re-read on EVERY tick, so
+ *  disarming stops the very next one. Nothing secret lives here, so no
+ *  encryption — same shape as `__confirmMode`/`__memoryPersist` above. */
 const AUTO_DRAIN_NAMESPACE = '__autoDrain';
 
-/** Reserved namespace for the auto-mint (seal-on-quiet) opt-in:
+/** Reserved namespace for the auto-mint (seal-on-quiet) switch:
  *  `{ enabled, publish }` — app-level, not a provider.
  *
- *  DEFAULT OFF for the same reason as auto-drain, and `publish` is a second,
- *  independent opt-in: sealing writes a local record, whereas publishing sends
- *  those bytes to the vault over `rclone` and writes an anchor beside them. An
- *  automatic network copy is never implied by an automatic seal.
+ *  `enabled` is DEFAULT ON, same as auto-drain: a session seals itself once it
+ *  has been quiet, with nothing on screen asking for it. Only an explicit
+ *  `enabled: false` disarms it.
+ *
+ *  `publish` stays a separate, DEFAULT OFF switch: sealing writes a local
+ *  record, whereas publishing sends those bytes to the vault over `rclone` and
+ *  writes an anchor beside them. An automatic network copy is never implied by
+ *  an automatic seal.
  *
  *  The AI half of the record resolves through the shared rungs in
  *  client/attest.js (`$AEGIS_AI_SECRET`/`$AEGIS_AI_MODEL` in the app scope) —
@@ -195,6 +211,7 @@ const RESERVED_NAMESPACES = Object.freeze([
   AEGIS_KEY_NAMESPACE,
   LEGACY_AEGIS_NAMESPACE,
   QUICK_LAUNCHER_NAMESPACE,
+  VAULT_BACKEND_NAMESPACE,
   CONFIRM_MODE_NAMESPACE,
   MEMORY_PERSIST_NAMESPACE,
   AVATAR_NAMESPACE,
@@ -539,6 +556,24 @@ function createSettingsStore({ dir, safeStorage, prefsDir, env } = {}) {
     return quickLauncherConfig();
   }
 
+  // --- Vault backend: reserved namespace, plain (unencrypted) preference ---
+  // No secret lives here either — just which of three named destinations a
+  // publish goes to — so like the quick launcher there is nothing to encrypt.
+
+  function vaultBackendConfig() {
+    const cfg = load()[VAULT_BACKEND_NAMESPACE] || {};
+    const backend = VAULT_BACKEND_VALUES.includes(cfg.backend) ? cfg.backend : DEFAULT_VAULT_BACKEND;
+    return { backend };
+  }
+
+  function setVaultBackendConfig(backend) {
+    if (!VAULT_BACKEND_VALUES.includes(backend)) return vaultBackendConfig();
+    const data = load();
+    data[VAULT_BACKEND_NAMESPACE] = { backend };
+    save(data);
+    return vaultBackendConfig();
+  }
+
   // --- Confirm mode: SHARED preference (AEGISONE ON8, decision D8 rule 1) --
   // "Confirm before running tools" — the switch for the renderer's tool-call
   // approval gate (desktop/lib/local/engine.js gatedExecuteTool). ON (default,
@@ -726,10 +761,10 @@ function createSettingsStore({ dir, safeStorage, prefsDir, env } = {}) {
   function getAutoDrain() {
     const cfg = load()[AUTO_DRAIN_NAMESPACE] || {};
     return {
-      // Unset === false. This is the opposite of confirm mode/memory persist,
-      // and it is the whole point of the feature: nothing drains itself until
-      // someone says so in as many words.
-      enabled: cfg.enabled === true,
+      // Unset === TRUE. The queue drains in the background unless someone
+      // switched it off in as many words; `lib/auto.js` re-reads this on every
+      // tick, so that off switch stops the very next one.
+      enabled: cfg.enabled !== false,
       intervalMs: clampAutoDrainInterval(cfg.intervalMs),
     };
   }
@@ -760,7 +795,8 @@ function createSettingsStore({ dir, safeStorage, prefsDir, env } = {}) {
   function getAutoMint() {
     const cfg = load()[AUTO_MINT_NAMESPACE] || {};
     return {
-      enabled: cfg.enabled === true,
+      // Unset === TRUE (background sealing). `publish` below stays opt-in.
+      enabled: cfg.enabled !== false,
       // Independent of `enabled` on purpose: an automatic seal must not drag
       // an automatic upload along with it.
       publish: cfg.publish === true,
@@ -807,6 +843,8 @@ function createSettingsStore({ dir, safeStorage, prefsDir, env } = {}) {
     migrateLegacyAegisKey,
     quickLauncherConfig,
     setQuickLauncherConfig,
+    vaultBackendConfig,
+    setVaultBackendConfig,
     getConfirmMode,
     setConfirmMode,
     confirmModeState,
@@ -833,6 +871,7 @@ module.exports = {
   AEGIS_KEY_NAMESPACE,
   LEGACY_AEGIS_NAMESPACE,
   QUICK_LAUNCHER_NAMESPACE,
+  VAULT_BACKEND_NAMESPACE,
   CONFIRM_MODE_NAMESPACE,
   MEMORY_PERSIST_NAMESPACE,
   AVATAR_NAMESPACE,
@@ -844,6 +883,8 @@ module.exports = {
   AUTO_DRAIN_INTERVAL_MAX_MS,
   AVATAR_MOTION_MODES,
   DEFAULT_QUICK_LAUNCHER_SHORTCUT,
+  DEFAULT_VAULT_BACKEND,
+  VAULT_BACKEND_VALUES,
   RESERVED_NAMESPACES,
   isReservedNamespace,
   maskKey,