castle-web-cli 0.4.190 → 0.4.192

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -121,3 +121,6 @@ export declare function buildTaskPrompt(opts: {
121
121
  playtest?: boolean;
122
122
  }): string;
123
123
  export declare const CLAUDE_TASK_SYSTEM_REMINDER = "Castle background task agent: work autonomously to completion -- never pause to ask questions or wait for confirmation; finish the task end-to-end, then stop. Prefer the quickest viable change that fully does the job.";
124
+ export declare const MUSE_TASK_ADDENDUM = "Kit code rules for this deck. The kit guide documents every API you need; use exactly the names and signatures it gives and nothing else. Do not guess at APIs: no typeof checks on methods, no ?. or ?? fallbacks on documented objects, no try/catch around ordinary calls, no alternate spellings of a callback. One mechanism per feature, chosen for what the task asks (a tap on the actor is its onTap; a tap anywhere on the card is the pointer checked in update; a contact is onCollisionEnter): use that one and never also scan for the same event another way. Props come from defaultProps, so never repeat a default with ?? value. Find actors by the behavior or id the task names; never sniff ids like 'player' or 'ball' as fallbacks. Read the guide's gotchas for every API you use and follow them. Reference only files that exist in the deck tree or that you create in this task. Build everything the task names and only that: no extra input methods, actors, or polish it did not mention.";
125
+ export declare function isMuseModel(model: string): boolean;
126
+ export declare function modelTaskAddendum(model: string): string | undefined;
@@ -142,6 +142,7 @@ now- food-hauling
142
142
  - A bare number, a knob setting, or a bug they want gone is not taste -- just do the tweak. The REASON they give for one is: "make the islands bigger, it's already pretty hard" is a \`decide+\` about the difficulty they want, not about island size.
143
143
  - Put the fence AFTER your task fences: tasks spawn the moment their fence closes, so one in front just delays the user's first build.
144
144
  - NOTHING in \`## Open questions\` may be answered by anything else in the same reply, fence or task: asking and deciding are different acts. A probe IS the top open question, asked in its own words.
145
+ - An open question you have asked outright twice, and the user passed over both times, is TABLED: \`open- <label>\` it in that reply's fence and stop asking it. Passing over it twice is their answer about the question. It comes back only if they bring it up.
145
146
  - An ask that goes against a \`## Decisions\` line: say what was decided and why in one sentence BEFORE you build it. They may well have changed their mind -- that is theirs to say, and the line is yours to raise.
146
147
  - No plan.md yet and the deck is getting work? Open one here with the ops the moment supports: an \`identity:\` line, the \`## Now\` items you are spawning, an \`open+\` for what you are guessing at. SPARSE AND TRUE, and never in place of their actual ask.
147
148
 
@@ -1001,3 +1002,13 @@ phase: wiring the paddle to touch
1001
1002
  // Appended to claude task agents' system prompt (portable replacement for the
1002
1003
  // machine-specific /goal slash command): commit to autonomous completion.
1003
1004
  export const CLAUDE_TASK_SYSTEM_REMINDER = "Castle background task agent: work autonomously to completion -- never pause to ask questions or wait for confirmation; finish the task end-to-end, then stop. Prefer the quickest viable change that fully does the job.";
1005
+ // Meta's muse models hedge on uncertain kit APIs with typeof probes, several
1006
+ // callback spellings, and per-frame scans beside callbacks. These rules apply to
1007
+ // muse task agents only; other models are untouched.
1008
+ export const MUSE_TASK_ADDENDUM = "Kit code rules for this deck. The kit guide documents every API you need; use exactly the names and signatures it gives and nothing else. Do not guess at APIs: no typeof checks on methods, no ?. or ?? fallbacks on documented objects, no try/catch around ordinary calls, no alternate spellings of a callback. One mechanism per feature, chosen for what the task asks (a tap on the actor is its onTap; a tap anywhere on the card is the pointer checked in update; a contact is onCollisionEnter): use that one and never also scan for the same event another way. Props come from defaultProps, so never repeat a default with ?? value. Find actors by the behavior or id the task names; never sniff ids like 'player' or 'ball' as fallbacks. Read the guide's gotchas for every API you use and follow them. Reference only files that exist in the deck tree or that you create in this task. Build everything the task names and only that: no extra input methods, actors, or polish it did not mention.";
1009
+ export function isMuseModel(model) {
1010
+ return /muse/i.test(model);
1011
+ }
1012
+ export function modelTaskAddendum(model) {
1013
+ return isMuseModel(model) ? MUSE_TASK_ADDENDUM : undefined;
1014
+ }
package/dist/agent.d.ts CHANGED
@@ -3,11 +3,14 @@ import { Duplex } from 'stream';
3
3
  import { type PlaytestToolResult } from './native/playtest.js';
4
4
  export declare const AGENT_WS_PATH = "/__castle/agent";
5
5
  export type ClaudeModel = 'sonnet' | 'opus' | 'fable' | 'openrouter';
6
+ export type EffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
6
7
  interface AgentSettings {
7
8
  routerClaudeModel: ClaudeModel;
8
9
  tasksClaudeModel: ClaudeModel;
9
10
  routerOpenrouterModel: string;
10
11
  tasksOpenrouterModel: string;
12
+ routerEffort: EffortLevel;
13
+ tasksEffort: EffortLevel;
11
14
  }
12
15
  type OpenrouterSlugKey = 'routerOpenrouterModel' | 'tasksOpenrouterModel';
13
16
  type SettingsWarnings = Partial<Record<OpenrouterSlugKey, {
package/dist/agent.js CHANGED
@@ -14,7 +14,7 @@
14
14
  // Backend CLI: the claude CLI in headless print mode (stream-json), behind
15
15
  // runAgentCli.
16
16
  import { execFileSync, spawn } from 'child_process';
17
- import { quickReferenceFor } from './platformDoc.js';
17
+ import { claudeContextEnv, quickReferenceFor } from './platformDoc.js';
18
18
  import { IMPORTS_DIR } from './imports.js';
19
19
  import { isSameOriginUpgrade } from './wsOrigin.js';
20
20
  import { resolveDeckPath } from './ide.js';
@@ -27,7 +27,7 @@ import { WebSocketServer } from 'ws';
27
27
  import { rawDataToString } from './rawData.js';
28
28
  import { atomicWriteFileSync } from './atomicFile.js';
29
29
  import { AGENT_ATTACHMENT_PREFIX, AGENT_PLAYTEST_PREFIX, PLAN_FILE } from './localPaths.js';
30
- import { applyPlanOps, buildRouterPromptParts, buildTaskPrompt, parsePlanOps, planOpenQuestionLines, truncateToBytes, userTurnInstruction, CLAUDE_TASK_SYSTEM_REMINDER, } from './agent-prompts.js';
30
+ import { applyPlanOps, buildRouterPromptParts, buildTaskPrompt, parsePlanOps, planOpenQuestionLines, truncateToBytes, userTurnInstruction, CLAUDE_TASK_SYSTEM_REMINDER, modelTaskAddendum, isMuseModel, } from './agent-prompts.js';
31
31
  import { readCastleJson } from './castleJson.js';
32
32
  import { checkOpenrouterKey, checkOpenrouterModel, primeOpenrouterCatalog, } from './openrouter-catalog.js';
33
33
  import { classifyProviderError, failureCopy, setReaderTimeZone, } from './agent-failures.js';
@@ -55,6 +55,8 @@ const DEFAULT_SETTINGS = {
55
55
  // castleSpendRefusal. Picking any other slug puts that role back on credits.
56
56
  routerOpenrouterModel: 'meta/muse-spark-1.3-contributor',
57
57
  tasksOpenrouterModel: 'meta/muse-spark-1.3-contributor',
58
+ routerEffort: 'medium',
59
+ tasksEffort: 'medium',
58
60
  };
59
61
  // What the two claude-model defaults become once the user has an Anthropic
60
62
  // credential of their own -- a key or a claude.ai login, which
@@ -70,10 +72,26 @@ const ANTHROPIC_DEFAULT_MODELS = {
70
72
  // appears and disappears mid-session (the Accounts modal, `claude /login` in
71
73
  // the terminal panel, a hand-edited user-keys.json), and
72
74
  // refreshDefaultedSettings re-reads it when it does.
75
+ // The effort a role starts at for a given model. Tasks on a muse model start
76
+ // at low: castle-agent-evals/muse-tune measured medium as slower with more api
77
+ // guessing. The operator stays at medium on every model, and claude models
78
+ // stay at medium for both roles. A level the user picks is stored and stands.
79
+ function defaultEffortFor(role, claudeModel, openrouterModel) {
80
+ return role === 'tasks' && claudeModel === 'openrouter' && isMuseModel(openrouterModel) ? 'low' : 'medium';
81
+ }
82
+ const EFFORT_ROLES = [
83
+ { role: 'router', label: 'operator', claude: 'routerClaudeModel', slug: 'routerOpenrouterModel', effort: 'routerEffort' },
84
+ { role: 'tasks', label: 'tasks', claude: 'tasksClaudeModel', slug: 'tasksOpenrouterModel', effort: 'tasksEffort' },
85
+ ];
73
86
  function defaultSettings() {
74
- return resolveAnthropicAuth().mode === 'proxy'
87
+ const models = resolveAnthropicAuth().mode === 'proxy'
75
88
  ? { ...DEFAULT_SETTINGS }
76
89
  : { ...DEFAULT_SETTINGS, ...ANTHROPIC_DEFAULT_MODELS };
90
+ return {
91
+ ...models,
92
+ routerEffort: defaultEffortFor('router', models.routerClaudeModel, models.routerOpenrouterModel),
93
+ tasksEffort: defaultEffortFor('tasks', models.tasksClaudeModel, models.tasksOpenrouterModel),
94
+ };
77
95
  }
78
96
  // Bump to force every deck onto the current DEFAULT_SETTINGS once, discarding
79
97
  // what users had chosen: a stored file below this epoch has ALL of its setting
@@ -120,6 +138,15 @@ function normalizeOpenrouterModel(value) {
120
138
  const trimmed = value.trim();
121
139
  return trimmed && trimmed.length <= OPENROUTER_MODEL_MAX_LEN ? trimmed : null;
122
140
  }
141
+ function normalizeEffort(value) {
142
+ return value === 'low' ||
143
+ value === 'medium' ||
144
+ value === 'high' ||
145
+ value === 'xhigh' ||
146
+ value === 'max'
147
+ ? value
148
+ : null;
149
+ }
123
150
  // Every setting's validator, keyed the same as AgentSettings, so load and save
124
151
  // iterate one list rather than repeating the field names per direction.
125
152
  const SETTING_NORMALIZERS = {
@@ -127,6 +154,8 @@ const SETTING_NORMALIZERS = {
127
154
  tasksClaudeModel: normalizeClaudeModel,
128
155
  routerOpenrouterModel: normalizeOpenrouterModel,
129
156
  tasksOpenrouterModel: normalizeOpenrouterModel,
157
+ routerEffort: normalizeEffort,
158
+ tasksEffort: normalizeEffort,
130
159
  };
131
160
  const SETTING_KEYS = Object.keys(SETTING_NORMALIZERS);
132
161
  // Sparse ON PURPOSE: only fields that DIFFER from the current defaults are
@@ -150,6 +179,16 @@ function serializeAgentSettings(settings) {
150
179
  if (settings[key] !== defaults[key])
151
180
  out[key] = settings[key];
152
181
  }
182
+ // Effort's default follows the role's stored model, not the default model.
183
+ for (const role of EFFORT_ROLES) {
184
+ const value = settings[role.effort];
185
+ if (value === defaultEffortFor(role.role, settings[role.claude], settings[role.slug])) {
186
+ delete out[role.effort];
187
+ }
188
+ else {
189
+ out[role.effort] = value;
190
+ }
191
+ }
153
192
  return JSON.stringify(out, null, 2) + '\n';
154
193
  }
155
194
  function loadAgentSettings(settingsPath) {
@@ -170,7 +209,14 @@ function loadAgentSettings(settingsPath) {
170
209
  if (value !== null)
171
210
  overrides[key] = value;
172
211
  }
173
- return { ...defaults, ...overrides };
212
+ const merged = { ...defaults, ...overrides };
213
+ for (const role of EFFORT_ROLES) {
214
+ if (role.effort in overrides) {
215
+ continue;
216
+ }
217
+ merged[role.effort] = defaultEffortFor(role.role, merged[role.claude], merged[role.slug]);
218
+ }
219
+ return merged;
174
220
  }
175
221
  // Re-resolve the defaults into the live settings object after a credential
176
222
  // change, in place because every consumer (the router queue, the task store)
@@ -265,7 +311,7 @@ function openrouterApiKey() {
265
311
  // Build the headless CLI invocation for a role. Hosted claude runs
266
312
  // bypassPermissions for both roles because the container is already the
267
313
  // permission boundary. Local claude stays on auto (NOT plan mode -- that makes it emit plan tool calls)
268
- // at medium effort. claudeModel "openrouter" keeps the SAME claude binary and
314
+ // at the role's effort setting. claudeModel "openrouter" keeps the SAME claude binary and
269
315
  // swaps only the model slug and env (see envForOpenrouterSpawn).
270
316
  // claude CLI 2.1.198 SILENTLY resolves `--permission-mode auto` to "default"
271
317
  // whenever --model is not in its built-in catalog -- which is every free-form
@@ -329,25 +375,10 @@ function claudeSettingsArg(auth) {
329
375
  ...(auth?.mode === 'user-key' ? { apiKeyHelper: anthropicKeyHelperCommand() } : {}),
330
376
  });
331
377
  }
332
- // The claude CLI puts every CLAUDE.md it finds, and a git-status note, into the
333
- // first user message of each process, ahead of the prompt. A router turn is a
334
- // new process, so that text (the kit guide: ~23k tokens on a kit deck) is sent
335
- // uncached on every call of every turn. The router already carries the deck's
336
- // quick reference and file tree in its cached system part, and can read a
337
- // guide on demand; tasks keep the CLI's own loading. Auto memory is off for the
338
- // same reason: the first process in a deck creates the memory store, the next
339
- // one's system prompt gains a memory block, and the cached prefix only matches
340
- // from the third turn on. Measured on a 30k-token router prompt: a second turn
341
- // goes from 50k tokens written to 6k.
342
- const ROUTER_CLAUDE_ENV = {
343
- CLAUDE_CODE_DISABLE_CLAUDE_MDS: '1',
344
- CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS: '1',
345
- CLAUDE_CODE_DISABLE_AUTO_MEMORY: '1',
346
- };
347
378
  function buildAgentInvocation(role, prompt, claudeModel,
348
379
  // Already resolved for this role by the caller (router turns pass
349
380
  // settings.routerOpenrouterModel, task spawns settings.tasksOpenrouterModel).
350
- openrouterModel,
381
+ openrouterModel, effort,
351
382
  // This run's ledger identity, and the deck dir its castle.json is read from.
352
383
  metering,
353
384
  // The task this spawn belongs to, so its playtest frames land under
@@ -357,11 +388,12 @@ taskId,
357
388
  // The stable part of a router prompt, passed as appended system text so the
358
389
  // CLI's own cache breakpoints cover it.
359
390
  systemPrompt) {
360
- const systemText = [systemPrompt, role === 'task' ? CLAUDE_TASK_SYSTEM_REMINDER : undefined]
391
+ const viaOpenrouter = claudeModel === 'openrouter';
392
+ const spawnModel = viaOpenrouter ? openrouterModel : claudeModel;
393
+ const systemText = [systemPrompt, role === 'task' ? CLAUDE_TASK_SYSTEM_REMINDER : undefined, role === 'task' ? modelTaskAddendum(spawnModel) : undefined]
361
394
  .filter((text) => Boolean(text))
362
395
  .join('\n\n');
363
396
  const hosted = Boolean(process.env.CASTLE_SANDBOX_ID);
364
- const viaOpenrouter = claudeModel === 'openrouter';
365
397
  const orAuth = viaOpenrouter ? resolveOpenrouterAuth() : null;
366
398
  const anAuth = viaOpenrouter ? null : resolveAnthropicAuth();
367
399
  // Direct = the user's own credential/login is in play, so this run bypasses
@@ -380,9 +412,9 @@ systemPrompt) {
380
412
  hosted ? 'bypassPermissions' : 'auto',
381
413
  ...(!hosted && viaOpenrouter ? [openrouterAllowedToolsArg(role)] : []),
382
414
  '--model',
383
- viaOpenrouter ? openrouterModel : claudeModel,
415
+ spawnModel,
384
416
  '--effort',
385
- 'medium',
417
+ effort,
386
418
  // Newer claude models default thinking display to "omitted" (empty
387
419
  // thinking_delta text, signature only); "summarized" restores actual
388
420
  // summary text so the shell's expandable thinking transcript has
@@ -404,7 +436,7 @@ systemPrompt) {
404
436
  route: viaOpenrouter ? 'openrouter' : 'anthropic',
405
437
  direct,
406
438
  })),
407
- ...(role === 'router' ? ROUTER_CLAUDE_ENV : {}),
439
+ ...claudeContextEnv(role),
408
440
  // Claude Code 2.1.258 refuses bypassPermissions as root unless the
409
441
  // child explicitly identifies itself as running in a sandbox.
410
442
  ...(hosted ? { IS_SANDBOX: '1' } : {}),
@@ -1663,7 +1695,7 @@ async function runAgentTurn(opts) {
1663
1695
  // conversation -- nothing is resumed).
1664
1696
  const sessionId = newAgentSessionId(opts.role);
1665
1697
  const settled = (run) => run.finally(() => notifyAgentRunFinished());
1666
- const invocation = buildAgentInvocation(opts.role, opts.prompt, opts.claudeModel, opts.openrouterModel, { sessionId, deckDir: opts.cwd }, opts.taskId, opts.systemPrompt);
1698
+ const invocation = buildAgentInvocation(opts.role, opts.prompt, opts.claudeModel, opts.openrouterModel, opts.effort, { sessionId, deckDir: opts.cwd }, opts.taskId, opts.systemPrompt);
1667
1699
  const run = runAgentCli({
1668
1700
  cwd: opts.cwd,
1669
1701
  command: invocation.command,
@@ -1965,7 +1997,7 @@ async function runTaskAgentIn(ctx, task) {
1965
1997
  depsSummary: ctx.depsSummary,
1966
1998
  playtest: playtestSteering(),
1967
1999
  deckTree: buildDeckTree(ctx.deckDir),
1968
- quickReference: quickReferenceFor(ctx.deckDir, ctx.quickReference),
2000
+ quickReference: quickReferenceFor(ctx.deckDir, ctx.quickReference, 'task'),
1969
2001
  plan: taskPlanOpts(ctx.deckDir, task.item, ctx.finishedWork),
1970
2002
  siblings: ctx.siblings,
1971
2003
  });
@@ -2018,6 +2050,7 @@ async function runTaskAgentIn(ctx, task) {
2018
2050
  prompt: taskPrompt,
2019
2051
  claudeModel: ctx.claudeModel,
2020
2052
  openrouterModel: ctx.openrouterModel,
2053
+ effort: ctx.effort,
2021
2054
  cwd: ctx.deckDir,
2022
2055
  timeoutMs: TASK_TIMEOUT_MS,
2023
2056
  logPath: path.join(dir, 'log.jsonl'),
@@ -2074,6 +2107,7 @@ function startTask(ctx, task) {
2074
2107
  children: ctx.children,
2075
2108
  claudeModel: ctx.claudeModel(),
2076
2109
  openrouterModel: ctx.openrouterModel(),
2110
+ effort: ctx.effort(),
2077
2111
  stopRequested: ctx.stopRequested,
2078
2112
  quickReference: ctx.quickReference,
2079
2113
  playtest: ctx.playtest,
@@ -2281,6 +2315,7 @@ function createTaskStore(opts) {
2281
2315
  quickReference: opts.quickReference,
2282
2316
  claudeModel: opts.claudeModel,
2283
2317
  openrouterModel: opts.openrouterModel,
2318
+ effort: opts.effort,
2284
2319
  playtest: opts.playtest,
2285
2320
  onStarted: opts.onStarted,
2286
2321
  onFinished: opts.onFinished,
@@ -2778,7 +2813,7 @@ function resolveFailure(result) {
2778
2813
  function routerTurnPrompt(ctx, instruction, selfMessageId, plan) {
2779
2814
  return buildRouterPromptParts({
2780
2815
  deckLabel: ctx.deckLabel,
2781
- quickReference: quickReferenceFor(ctx.deckDir, ctx.quickReference),
2816
+ quickReference: quickReferenceFor(ctx.deckDir, ctx.quickReference, 'router'),
2782
2817
  deckTree: buildDeckTree(ctx.deckDir),
2783
2818
  playtest: playtestSteering(),
2784
2819
  messages: ctx.log.messages
@@ -2908,6 +2943,7 @@ function runRouterTurnIn(ctx, instruction) {
2908
2943
  systemPrompt: prompt.system,
2909
2944
  claudeModel: ctx.claudeModel(),
2910
2945
  openrouterModel: ctx.openrouterModel(),
2946
+ effort: ctx.effort(),
2911
2947
  cwd: ctx.deckDir,
2912
2948
  timeoutMs: ROUTER_TIMEOUT_MS,
2913
2949
  logPath: path.join(ctx.agentDir, 'router-log.jsonl'),
@@ -3102,6 +3138,27 @@ function applyAgentSettings(incoming, ctx) {
3102
3138
  changes.push(`${key === 'routerOpenrouterModel' ? 'operator' : 'tasks'} openrouter model -> ${value}`);
3103
3139
  }
3104
3140
  }
3141
+ for (const key of ['routerEffort', 'tasksEffort']) {
3142
+ const value = normalizeEffort(incoming[key]);
3143
+ if (value && value !== settings[key]) {
3144
+ settings[key] = value;
3145
+ changes.push(`${key === 'routerEffort' ? 'operator' : 'tasks'} effort -> ${value}`);
3146
+ }
3147
+ }
3148
+ // A role whose model just changed takes that model's default effort, unless
3149
+ // this same message chose one. The reset is written and broadcast like any
3150
+ // other change, so the picker shows the level the next spawn will use.
3151
+ for (const role of EFFORT_ROLES) {
3152
+ const modelChanged = changes.some((c) => c.startsWith(`${role.label} claude model`) || c.startsWith(`${role.label} openrouter model`));
3153
+ if (!modelChanged || normalizeEffort(incoming[role.effort])) {
3154
+ continue;
3155
+ }
3156
+ const value = defaultEffortFor(role.role, settings[role.claude], settings[role.slug]);
3157
+ if (value !== settings[role.effort]) {
3158
+ settings[role.effort] = value;
3159
+ changes.push(`${role.label} effort -> ${value} (default for this model)`);
3160
+ }
3161
+ }
3105
3162
  if (changes.length === 0)
3106
3163
  return;
3107
3164
  atomicWriteFileSync(ctx.settingsPath, serializeAgentSettings(settings));
@@ -3394,6 +3451,7 @@ function startRouterTurn(ctx, instruction) {
3394
3451
  currentEpoch: () => ctx.state.userEpoch,
3395
3452
  claudeModel: () => ctx.settings.routerClaudeModel,
3396
3453
  openrouterModel: () => ctx.settings.routerOpenrouterModel,
3454
+ effort: () => ctx.settings.routerEffort,
3397
3455
  canAutoRetry: () => !ctx.state.autoRetryUsed && ctx.state.pendingSends.length === 0,
3398
3456
  onSettled: (retryable) => onRouterQueueSettled(ctx, retryable),
3399
3457
  }, instruction);
@@ -3770,6 +3828,7 @@ export function createAgentServer(opts) {
3770
3828
  quickReference,
3771
3829
  openrouterModel: () => settings.tasksOpenrouterModel,
3772
3830
  claudeModel: () => settings.tasksClaudeModel,
3831
+ effort: () => settings.tasksEffort,
3773
3832
  playtest,
3774
3833
  // Task lifecycle stays on the board only -- log lines for it were spam.
3775
3834
  onUpdate: (task) => broadcast({ type: 'task-update', task: asClientTask(task, opts.signPath) }),
@@ -1,9 +1,10 @@
1
1
  export declare const PLATFORM_DOCS_DIR: string;
2
2
  export declare const PLATFORM_DOC_REL: string;
3
3
  export declare function everyDeckBullets(deckDir: string): string[];
4
- export declare const PLATFORM_SECTION_HEADING = "### from the Castle platform (every deck)";
5
- export declare function platformSection(deckDir: string): string;
6
- export declare function quickReferenceFor(deckDir: string, quickReference: string): string;
4
+ export type AgentRole = 'router' | 'task';
5
+ export declare function roleLoadsClaudeMd(role: AgentRole): boolean;
6
+ export declare function claudeContextEnv(role: AgentRole): NodeJS.ProcessEnv;
7
+ export declare function quickReferenceFor(deckDir: string, quickReference: string, role: AgentRole): string;
7
8
  export declare function platformGuide(deckDir: string): string;
8
9
  export declare function writePlatformDocs(deckDir: string): void;
9
10
  export declare const CLAUDE_MD_IMPORT_LINE: string;
@@ -7,8 +7,9 @@ import { resolveFileTypes } from './editorConfig.js';
7
7
  // editors. Its one home is here. The serve writes it under the deck's .castle/
8
8
  // at every start (runtime state: not saved, not versioned, never edited), the
9
9
  // deck's root CLAUDE.md `@`-imports the compact copy so any agent that
10
- // auto-loads CLAUDE.md gets it for free, and backends that read no CLAUDE.md
11
- // get the same bullets in their composed prompt. Kits
10
+ // auto-loads CLAUDE.md gets it for free, and a role whose claude loads no
11
+ // CLAUDE.md gets the every-deck bullets in its composed prompt instead
12
+ // (roleLoadsClaudeMd below decides that once, for both sides). Kits
12
13
  // state only what is theirs; nothing below is restated in a kit's guide.
13
14
  //
14
15
  // The text is what was always in context before it had one home: the four
@@ -59,12 +60,6 @@ export function everyDeckBullets(deckDir) {
59
60
  MODE_BULLET,
60
61
  ];
61
62
  }
62
- // The guide as a section of the prompt's "how this deck works", for the
63
- // backends that read no CLAUDE.md. Same heading shape as an import's section.
64
- export const PLATFORM_SECTION_HEADING = '### from the Castle platform (every deck)';
65
- export function platformSection(deckDir) {
66
- return `${PLATFORM_SECTION_HEADING}\n\n${platformGuide(deckDir)}`;
67
- }
68
63
  // ------------------------------------------------------------------- the gate
69
64
  // Whether this serve may rewrite an EXISTING deck's root CLAUDE.md onto the
70
65
  // @import. That rewrite is the one irreversible thing here, so it reaches decks
@@ -117,14 +112,47 @@ function withEveryDeckBullets(deckDir, quickReference) {
117
112
  const bullets = everyDeckBullets(deckDir).join('\n');
118
113
  return own ? `${own}\n\n${bullets}` : bullets;
119
114
  }
120
- // A deck's quick reference as the agent sees it. claude auto-loads the root
121
- // CLAUDE.md -- but only a deck whose file carries the @import line has the
122
- // guide that way. A deck the migration has not reached (gated off) or refused
123
- // ('kept' -- someone edited its sections) still has the four legacy sections
124
- // inline and is missing just the every-deck bullets, which left the kits'
125
- // quick reference in the same change that added the guide.
126
- export function quickReferenceFor(deckDir, quickReference) {
127
- return deckLoadsGuide(deckDir)
115
+ // Whether a role's claude process auto-loads the deck's CLAUDE.md, and with it
116
+ // the @imported platform guide. The ONE place that is decided: both consumers
117
+ // -- quickReferenceFor below and the spawn env in agent.ts -- derive from it.
118
+ //
119
+ // A router turn is a new process every turn, and the claude CLI puts every
120
+ // CLAUDE.md it finds, a git-status note and the auto-memory block into that
121
+ // process's first user message, ahead of the prompt and uncached: the kit
122
+ // guide alone is ~23k tokens on a kit deck, sent again on every call of every
123
+ // turn. So the router carries the deck's quick reference (and file tree) in
124
+ // its cached system part instead and reads a guide on demand; tasks keep the
125
+ // CLI's own loading. Measured on a 30k-token router prompt: a second turn goes
126
+ // from 50k tokens written to 6k. (6d974dc turned the loading off; the
127
+ // regression 330075e had to fix is what happens when one of the two consumers
128
+ // moves and the other does not.)
129
+ export function roleLoadsClaudeMd(role) {
130
+ return role === 'task';
131
+ }
132
+ // The env for a claude spawn of this role: the CLI's own context injection
133
+ // switched off for a role that loads no CLAUDE.md, nothing for one that does.
134
+ // Auto memory rides along for the same cache reason -- the first process in a
135
+ // deck creates the memory store, the next one's system prompt gains a memory
136
+ // block, and the cached prefix only matches from the third turn on.
137
+ export function claudeContextEnv(role) {
138
+ return roleLoadsClaudeMd(role)
139
+ ? {}
140
+ : {
141
+ CLAUDE_CODE_DISABLE_CLAUDE_MDS: '1',
142
+ CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS: '1',
143
+ CLAUDE_CODE_DISABLE_AUTO_MEMORY: '1',
144
+ };
145
+ }
146
+ // A deck's quick reference as one agent role sees it. A task's claude
147
+ // auto-loads the root CLAUDE.md -- but only a deck whose file carries the
148
+ // @import line has the guide that way. A deck the migration has not reached
149
+ // (gated off) or refused ('kept' -- someone edited its sections) still has the
150
+ // four legacy sections inline and is missing just the every-deck bullets, which
151
+ // left the kits' quick reference in the same change that added the guide. A
152
+ // role that loads no CLAUDE.md (roleLoadsClaudeMd) takes the bullets here
153
+ // whatever the deck's file says.
154
+ export function quickReferenceFor(deckDir, quickReference, role) {
155
+ return roleLoadsClaudeMd(role) && deckLoadsGuide(deckDir)
128
156
  ? quickReference
129
157
  : withEveryDeckBullets(deckDir, quickReference);
130
158
  }