@venizia/vulcan 0.4.9-0 → 0.4.9-2

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.
Files changed (141) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +2 -2
  3. package/base/hooks/codex-guards.ts +15 -5
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +4 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +5 -6
  8. package/base/hooks/guard-remote-hosts.ts +6 -7
  9. package/base/hooks/guard-scripting.ts +5 -6
  10. package/base/hooks/guard-writes.ts +8 -9
  11. package/base/hooks/post-tool.ts +2 -2
  12. package/base/hooks/prompt-submit.ts +2 -2
  13. package/base/hooks/session-start.ts +3 -3
  14. package/base/hooks/stop.ts +2 -2
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/skills/docs-update/SKILL.md +4 -2
  17. package/base/skills/visualize-work/SKILL.md +9 -0
  18. package/package.json +3 -3
  19. package/src/agents/atlas-block.ts +43 -43
  20. package/src/agents/codex-hooks.ts +45 -43
  21. package/src/agents/detect.ts +19 -16
  22. package/src/agents/exclude.ts +96 -97
  23. package/src/agents/hooks-json.ts +38 -36
  24. package/src/agents/local.ts +46 -43
  25. package/src/agents/prompt.ts +45 -42
  26. package/src/agents/render.ts +201 -195
  27. package/src/agents/resolve.ts +133 -134
  28. package/src/agents/table.ts +12 -8
  29. package/src/commands/add.command.ts +2 -2
  30. package/src/commands/agents.command.ts +11 -17
  31. package/src/commands/clean.command.ts +6 -6
  32. package/src/commands/doctor.command.ts +4 -4
  33. package/src/commands/init.command.ts +12 -8
  34. package/src/commands/preset.command.ts +2 -2
  35. package/src/commands/profile.command.ts +42 -49
  36. package/src/commands/sync.command.ts +109 -111
  37. package/src/commands/upgrade.command.ts +80 -75
  38. package/src/commands/visualize.command.ts +7 -13
  39. package/src/commands/x.command.ts +55 -50
  40. package/src/common/format.ts +23 -21
  41. package/src/common/json.ts +8 -5
  42. package/src/common/layout-folder.ts +94 -91
  43. package/src/common/paths.ts +14 -12
  44. package/src/config/loader.ts +52 -49
  45. package/src/config/packages.ts +14 -11
  46. package/src/config/schema.ts +3 -3
  47. package/src/create/add-app.ts +519 -509
  48. package/src/create/add-lib.ts +237 -240
  49. package/src/create/bunfig.ts +26 -23
  50. package/src/create/checks.ts +36 -34
  51. package/src/create/diff.ts +21 -23
  52. package/src/create/dockerignore.ts +26 -24
  53. package/src/create/files.ts +7 -5
  54. package/src/create/init-monorepo.ts +75 -80
  55. package/src/create/lib-preset.ts +59 -63
  56. package/src/create/manifest-json.ts +10 -4
  57. package/src/create/names.ts +217 -210
  58. package/src/create/next.ts +26 -23
  59. package/src/create/plan.ts +15 -12
  60. package/src/create/preset-diff.ts +301 -303
  61. package/src/create/preset-menu.ts +38 -32
  62. package/src/create/preset.ts +202 -197
  63. package/src/create/process.ts +79 -72
  64. package/src/create/scratch.ts +48 -49
  65. package/src/create/workspace.ts +404 -396
  66. package/src/doctor/checks.ts +1027 -1014
  67. package/src/doctor/makefile.ts +17 -13
  68. package/src/doctor/runner.ts +88 -118
  69. package/src/doctor/skills.ts +97 -95
  70. package/src/doctor/tags.ts +42 -37
  71. package/src/hooks/codex-patch.ts +25 -22
  72. package/src/hooks/command-view.ts +44 -39
  73. package/src/hooks/decision.ts +37 -37
  74. package/src/hooks/guard-git.ts +51 -49
  75. package/src/hooks/guard-manifest.ts +58 -55
  76. package/src/hooks/guard-outside.ts +93 -91
  77. package/src/hooks/guard-package.ts +82 -79
  78. package/src/hooks/guard-scripting.ts +19 -14
  79. package/src/hooks/guard-writes.ts +154 -149
  80. package/src/hooks/owner-reply.ts +127 -127
  81. package/src/hooks/post-tool.ts +94 -93
  82. package/src/hooks/project-guards.ts +65 -62
  83. package/src/hooks/project-tmp.ts +27 -24
  84. package/src/hooks/remote-hosts.ts +153 -130
  85. package/src/hooks/session-digest.ts +98 -101
  86. package/src/hooks/shell.ts +509 -499
  87. package/src/hooks/subagent-card.ts +11 -7
  88. package/src/hooks/trusted-scripts.ts +106 -104
  89. package/src/init/scaffold.ts +135 -132
  90. package/src/local/clean.ts +38 -36
  91. package/src/local/format.ts +21 -17
  92. package/src/local/scan.ts +144 -138
  93. package/src/manifest/render.ts +110 -104
  94. package/src/owner/card.ts +51 -46
  95. package/src/owner/profile.ts +99 -93
  96. package/src/owner/reply-switch.ts +9 -6
  97. package/src/owner/shape.ts +71 -69
  98. package/src/owner/survey.ts +173 -171
  99. package/src/owner/view.ts +62 -59
  100. package/src/owner/violations.ts +119 -123
  101. package/src/rules/base.ts +15 -11
  102. package/src/rules/parser.ts +39 -32
  103. package/src/rules/slots.ts +8 -6
  104. package/src/signals/claims.ts +30 -28
  105. package/src/signals/classify.ts +38 -33
  106. package/src/signals/loop.ts +39 -37
  107. package/src/signals/state.ts +79 -81
  108. package/src/skills/frontmatter.ts +28 -28
  109. package/src/sync/agent-files.ts +217 -199
  110. package/src/sync/agent-removal.ts +56 -59
  111. package/src/sync/atlas-block.ts +45 -43
  112. package/src/sync/base-rules.ts +32 -30
  113. package/src/sync/claude-launch.ts +36 -34
  114. package/src/sync/exclude.ts +77 -69
  115. package/src/sync/local-choice.ts +50 -47
  116. package/src/sync/planner.ts +59 -61
  117. package/src/sync/prune.ts +52 -48
  118. package/src/sync/settings.ts +166 -167
  119. package/src/ui/capability.ts +12 -7
  120. package/src/ui/keyboard.ts +38 -38
  121. package/src/ui/prompt.ts +79 -77
  122. package/src/visualize/assets.ts +33 -24
  123. package/src/visualize/charts.ts +179 -176
  124. package/src/visualize/compare-css.ts +3 -2
  125. package/src/visualize/compare-render.ts +9 -7
  126. package/src/visualize/diagrams.ts +189 -174
  127. package/src/visualize/grid-span.ts +34 -0
  128. package/src/visualize/icons.ts +7 -5
  129. package/src/visualize/kinds-render.ts +50 -45
  130. package/src/visualize/kinds-validate.ts +12 -10
  131. package/src/visualize/labels.ts +21 -17
  132. package/src/visualize/layout.ts +112 -97
  133. package/src/visualize/page.ts +92 -104
  134. package/src/visualize/render.ts +143 -140
  135. package/src/visualize/sections.ts +395 -384
  136. package/src/visualize/sources.ts +2 -2
  137. package/src/visualize/theme.ts +12 -10
  138. package/src/visualize/validate.ts +13 -9
  139. package/src/wiki/anchors.ts +38 -36
  140. package/src/wiki/command.ts +4 -4
  141. package/src/wiki/source-links.ts +46 -44
@@ -1,13 +1,9 @@
1
1
  import {
2
- appendSignal,
3
- callKeyOf,
4
2
  EntryKinds,
5
- gatesOf,
6
- isPublicProbe,
7
- loopOf,
8
- readSignals,
3
+ SignalClassifier,
9
4
  SignalConstants,
10
- watchedFileOf,
5
+ SignalLoop,
6
+ SignalState,
11
7
  WatchedKinds,
12
8
  } from '../signals/index.ts';
13
9
  import type { ISignalState } from '../signals/index.ts';
@@ -36,102 +32,107 @@ const reportsFailure = (opts: { response: Record<string, unknown> }): boolean =>
36
32
  );
37
33
  };
38
34
 
39
- /**
40
- * What the model is told after a tool call, and the line it adds to the turn's notes: whether the turn
41
- * asked public state, which gate commands ran and passed or failed, the calls themselves, so a loop shows.
42
- * It speaks only to say that the agent seems stuck, or that a skill or rules file was just changed; it
43
- * never blocks. Notes are kept per session, and a loop per agent. Input it cannot read gives no answer.
44
- */
45
- export const buildPostToolOutput = (opts: {
46
- projectRoot: string;
47
- input: unknown;
48
- now?: number;
49
- }): Record<string, unknown> | undefined => {
50
- const input = recordOf({ value: opts.input });
51
- const tool = stringOf({ value: input['tool_name'] });
52
-
53
- if (tool === '') {
54
- return undefined;
55
- }
56
-
57
- const now = opts.now ?? Date.now();
58
- const session = stringOf({ value: input['session_id'] });
59
- const agent = stringOf({ value: input['agent_id'] });
60
- const toolInput = recordOf({ value: input['tool_input'] });
61
- const event = input['hook_event_name'] === FAILURE_EVENT ? FAILURE_EVENT : 'PostToolUse';
62
- const isOk =
63
- event !== FAILURE_EVENT &&
64
- !reportsFailure({ response: recordOf({ value: input['tool_response'] }) });
65
- const command = stringOf({ value: toolInput['command'] });
66
- // A command sent to the background has not finished: its result is not known here.
67
- const isBackground = toolInput['run_in_background'] === true;
68
- const path = stringOf({ value: toolInput['file_path'] });
69
- const gates = tool === 'Bash' && !isBackground ? gatesOf({ command }) : [];
70
-
71
- try {
72
- appendSignal({
73
- root: opts.projectRoot,
74
- entry: {
75
- kind: EntryKinds.CALL,
76
- session,
77
- agent,
78
- at: now,
79
- tool,
80
- key: callKeyOf({ tool, input: toolInput }),
81
- isOk,
82
- isProbe: tool === 'Bash' && isOk && isPublicProbe({ command }),
83
- gates,
84
- isEdit: FILE_TOOLS.has(tool) && isOk,
85
- },
86
- });
87
- } catch {
88
- // The notes are advisory: a failed write costs a hint, never the call.
89
- }
90
-
91
- const state: ISignalState = readSignals({ root: opts.projectRoot, session, agent });
92
- const lines: string[] = [];
93
- const say = (name: string, line: string): void => {
94
- const last = state.notedAt[name];
95
-
96
- if (last !== undefined && now - last < SignalConstants.DEBOUNCE_MS) {
97
- return;
35
+ export class PostToolOutput {
36
+ /**
37
+ * What the model is told after a tool call, and the line it adds to the turn's notes: whether the turn
38
+ * asked public state, which gate commands ran and passed or failed, the calls themselves, so a loop shows.
39
+ * It speaks only to say that the agent seems stuck, or that a skill or rules file was just changed; it
40
+ * never blocks. Notes are kept per session, and a loop per agent. Input it cannot read gives no answer.
41
+ */
42
+ static build(opts: {
43
+ projectRoot: string;
44
+ input: unknown;
45
+ now?: number;
46
+ }): Record<string, unknown> | undefined {
47
+ const input = recordOf({ value: opts.input });
48
+ const tool = stringOf({ value: input['tool_name'] });
49
+
50
+ if (tool === '') {
51
+ return undefined;
98
52
  }
99
53
 
100
- lines.push(line);
54
+ const now = opts.now ?? Date.now();
55
+ const session = stringOf({ value: input['session_id'] });
56
+ const agent = stringOf({ value: input['agent_id'] });
57
+ const toolInput = recordOf({ value: input['tool_input'] });
58
+ const event = input['hook_event_name'] === FAILURE_EVENT ? FAILURE_EVENT : 'PostToolUse';
59
+ const isOk =
60
+ event !== FAILURE_EVENT &&
61
+ !reportsFailure({ response: recordOf({ value: input['tool_response'] }) });
62
+ const command = stringOf({ value: toolInput['command'] });
63
+ // A command sent to the background has not finished: its result is not known here.
64
+ const isBackground = toolInput['run_in_background'] === true;
65
+ const path = stringOf({ value: toolInput['file_path'] });
66
+ const gates = tool === 'Bash' && !isBackground ? SignalClassifier.gatesOf({ command }) : [];
101
67
 
102
68
  try {
103
- appendSignal({ root: opts.projectRoot, entry: { kind: EntryKinds.NOTE, at: now, name } });
69
+ SignalState.append({
70
+ root: opts.projectRoot,
71
+ entry: {
72
+ kind: EntryKinds.CALL,
73
+ session,
74
+ agent,
75
+ at: now,
76
+ tool,
77
+ key: SignalClassifier.callKeyOf({ tool, input: toolInput }),
78
+ isOk,
79
+ isProbe: tool === 'Bash' && isOk && SignalClassifier.isPublicProbe({ command }),
80
+ gates,
81
+ isEdit: FILE_TOOLS.has(tool) && isOk,
82
+ },
83
+ });
104
84
  } catch {
105
- // Without the note the advisory may repeat; nothing worse.
85
+ // The notes are advisory: a failed write costs a hint, never the call.
106
86
  }
107
- };
108
87
 
109
- if (FILE_TOOLS.has(tool) && isOk) {
110
- const watched = watchedFileOf({ path });
88
+ const state: ISignalState = SignalState.read({ root: opts.projectRoot, session, agent });
89
+ const lines: string[] = [];
90
+ const say = (name: string, line: string): void => {
91
+ const last = state.notedAt[name];
92
+
93
+ if (last !== undefined && now - last < SignalConstants.DEBOUNCE_MS) {
94
+ return;
95
+ }
96
+
97
+ lines.push(line);
98
+
99
+ try {
100
+ SignalState.append({
101
+ root: opts.projectRoot,
102
+ entry: { kind: EntryKinds.NOTE, at: now, name },
103
+ });
104
+ } catch {
105
+ // Without the note the advisory may repeat; nothing worse.
106
+ }
107
+ };
108
+
109
+ if (FILE_TOOLS.has(tool) && isOk) {
110
+ const watched = SignalClassifier.watchedFileOf({ path });
111
+
112
+ if (watched?.kind === WatchedKinds.SKILL) {
113
+ say(
114
+ `skill:${watched.name}`,
115
+ `You changed the skill ${watched.name}. Before you rely on it, run its evals (evals/evals.json) and read the transcripts: a skill change that no eval saw is a guess.`,
116
+ );
117
+ } else if (watched?.kind === WatchedKinds.RULES) {
118
+ say(
119
+ `rules:${watched.name}`,
120
+ 'You changed a rules file. A rule needs an observed failure and a named enforcement, and a mechanical check where one is possible (the retro skill states the admission bar).',
121
+ );
122
+ }
123
+ }
111
124
 
112
- if (watched?.kind === WatchedKinds.SKILL) {
113
- say(
114
- `skill:${watched.name}`,
115
- `You changed the skill ${watched.name}. Before you rely on it, run its evals (evals/evals.json) and read the transcripts: a skill change that no eval saw is a guess.`,
116
- );
117
- } else if (watched?.kind === WatchedKinds.RULES) {
125
+ const loop = SignalLoop.loopOf({ events: state.events });
126
+
127
+ if (loop !== undefined) {
118
128
  say(
119
- `rules:${watched.name}`,
120
- 'You changed a rules file. A rule needs an observed failure and a named enforcement, and a mechanical check where one is possible (the retro skill states the admission bar).',
129
+ `loop:${agent}`,
130
+ `Loop check: ${loop}. Stop repeating it: read the error, change the approach (the fix-a-bug skill builds the loop first), or ask the owner.`,
121
131
  );
122
132
  }
123
- }
124
133
 
125
- const loop = loopOf({ events: state.events });
126
-
127
- if (loop !== undefined) {
128
- say(
129
- `loop:${agent}`,
130
- `Loop check: ${loop}. Stop repeating it: read the error, change the approach (the fix-a-bug skill builds the loop first), or ask the owner.`,
131
- );
134
+ return lines.length === 0
135
+ ? undefined
136
+ : { hookSpecificOutput: { hookEventName: event, additionalContext: lines.join(' ') } };
132
137
  }
133
-
134
- return lines.length === 0
135
- ? undefined
136
- : { hookSpecificOutput: { hookEventName: event, additionalContext: lines.join(' ') } };
137
- };
138
+ }
@@ -89,70 +89,73 @@ const readOnlyScriptOf = (opts: { value: unknown }): IReadOnlyScript | undefined
89
89
  return { script, readOnly: words };
90
90
  };
91
91
 
92
- /**
93
- * The commands, push targets and read-only scripts a project lists, from the committed manifest (`vulcan sync` renders
94
- * them from the config), so a hook reads them with no config loader and no zod. A project with no
95
- * manifest, or none of the block, has none; an entry that cannot be used is skipped, said once on
96
- * stderr, and the others stay.
97
- */
98
- export const readGuardPolicy = (opts: { root: string }): IGuardPolicy => {
99
- const path = join(opts.root, GUARD_MANIFEST_FILE);
100
- const empty: IGuardPolicy = { commands: [], askPush: [] };
101
-
102
- if (!existsSync(path)) {
103
- return empty;
104
- }
105
-
106
- let manifest: unknown;
107
-
108
- try {
109
- manifest = JSON.parse(readFileSync(path, 'utf8'));
110
- } catch (error) {
111
- note({
112
- message: `the manifest could not be read, so the project's own patterns are off (${error instanceof Error ? error.message : String(error)})`,
92
+ export class ProjectGuards {
93
+ /**
94
+ * The commands, push targets and read-only scripts a project lists, from the committed manifest (`vulcan sync` renders
95
+ * them from the config), so a hook reads them with no config loader and no zod. A project with no
96
+ * manifest, or none of the block, has none; an entry that cannot be used is skipped, said once on
97
+ * stderr, and the others stay.
98
+ */
99
+ static readPolicy(opts: { root: string }): IGuardPolicy {
100
+ const path = join(opts.root, GUARD_MANIFEST_FILE);
101
+ const empty: IGuardPolicy = { commands: [], askPush: [] };
102
+
103
+ if (!existsSync(path)) {
104
+ return empty;
105
+ }
106
+
107
+ let manifest: unknown;
108
+
109
+ try {
110
+ manifest = JSON.parse(readFileSync(path, 'utf8'));
111
+ } catch (error) {
112
+ note({
113
+ message: `the manifest could not be read, so the project's own patterns are off (${error instanceof Error ? error.message : String(error)})`,
114
+ });
115
+
116
+ return empty;
117
+ }
118
+
119
+ const top = { value: manifest };
120
+ const guard = isRecord(top) ? { value: top.value['guard'] } : { value: undefined };
121
+
122
+ if (!isRecord(guard)) {
123
+ return empty;
124
+ }
125
+
126
+ const writes = { value: guard.value['writes'] };
127
+ const git = { value: guard.value['git'] };
128
+ const listed = isRecord(writes) ? writes.value['commands'] : undefined;
129
+ const scripts = isRecord(writes) ? writes.value['readOnlyScripts'] : undefined;
130
+ const targets = isRecord(git) ? git.value['askPush'] : undefined;
131
+ const readOnlyScripts = (Array.isArray(scripts) ? scripts : []).flatMap((entry) => {
132
+ const script = readOnlyScriptOf({ value: entry });
133
+
134
+ return script === undefined ? [] : [script];
113
135
  });
114
136
 
115
- return empty;
137
+ return {
138
+ commands: (Array.isArray(listed) ? listed : []).flatMap((entry) => {
139
+ const check = commandOf({ value: entry });
140
+
141
+ return check === undefined ? [] : [check];
142
+ }),
143
+ askPush: (Array.isArray(targets) ? targets : []).filter(
144
+ (target): target is string => typeof target === 'string' && target !== '',
145
+ ),
146
+ ...(readOnlyScripts.length === 0 ? {} : { readOnlyScripts }),
147
+ };
116
148
  }
117
149
 
118
- const top = { value: manifest };
119
- const guard = isRecord(top) ? { value: top.value['guard'] } : { value: undefined };
120
-
121
- if (!isRecord(guard)) {
122
- return empty;
150
+ /** Whether a branch name is one of the listed names; `*` stands for any run of characters, nothing else is special. */
151
+ static matchesBranch(opts: { name: string; patterns: string[] }): boolean {
152
+ return opts.patterns.some((pattern) =>
153
+ new RegExp(
154
+ `^${pattern
155
+ .split('*')
156
+ .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
157
+ .join('.*')}$`,
158
+ ).test(opts.name),
159
+ );
123
160
  }
124
-
125
- const writes = { value: guard.value['writes'] };
126
- const git = { value: guard.value['git'] };
127
- const listed = isRecord(writes) ? writes.value['commands'] : undefined;
128
- const scripts = isRecord(writes) ? writes.value['readOnlyScripts'] : undefined;
129
- const targets = isRecord(git) ? git.value['askPush'] : undefined;
130
- const readOnlyScripts = (Array.isArray(scripts) ? scripts : []).flatMap((entry) => {
131
- const script = readOnlyScriptOf({ value: entry });
132
-
133
- return script === undefined ? [] : [script];
134
- });
135
-
136
- return {
137
- commands: (Array.isArray(listed) ? listed : []).flatMap((entry) => {
138
- const check = commandOf({ value: entry });
139
-
140
- return check === undefined ? [] : [check];
141
- }),
142
- askPush: (Array.isArray(targets) ? targets : []).filter(
143
- (target): target is string => typeof target === 'string' && target !== '',
144
- ),
145
- ...(readOnlyScripts.length === 0 ? {} : { readOnlyScripts }),
146
- };
147
- };
148
-
149
- /** Whether a branch name is one of the listed names; `*` stands for any run of characters, nothing else is special. */
150
- export const matchesBranch = (opts: { name: string; patterns: string[] }): boolean =>
151
- opts.patterns.some((pattern) =>
152
- new RegExp(
153
- `^${pattern
154
- .split('*')
155
- .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
156
- .join('.*')}$`,
157
- ).test(opts.name),
158
- );
161
+ }
@@ -2,35 +2,38 @@ import { appendFileSync, mkdirSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
3
  import { HookConstants } from './common/index.ts';
4
4
 
5
- /** `<root>/.agents/local/tmp`: where a session's temporary files go, absolute. `vulcan clean` reads its age. */
6
- export const projectTmpOf = (opts: { root: string }): string =>
7
- join(opts.root, HookConstants.PROJECT_TMP);
8
-
9
5
  /** A word for `sh`, whatever it holds: in single quotes, a quote itself closed, escaped and opened again. */
10
6
  const shellQuote = (opts: { text: string }): string => `'${opts.text.replaceAll("'", "'\\''")}'`;
11
7
 
12
- /**
13
- * Makes every Bash command of a Claude Code session run with `TMPDIR` in the project. Claude Code hands a
14
- * SessionStart hook a file (`CLAUDE_ENV_FILE`) and sources it before each Bash command, so one `export`
15
- * there is enough: `mktemp`, bun, node and every script a command starts then use the project folder. It
16
- * does not move Claude Code's own task-output files or an MCP server (those need the launch file), and
17
- * `TMPDIR` in the project's settings `env` is not applied by Claude Code, which is why this is a hook.
18
- * Returns whether it wrote; with no file (another agent, a run outside Claude Code) it does nothing. A
19
- * path with a line break is refused: a line of shell must never be made from a folder name.
20
- */
21
- export const exportProjectTmp = (opts: { root: string; envFile: string | undefined }): boolean => {
22
- if (opts.envFile === undefined || opts.envFile === '') {
23
- return false;
8
+ export class ProjectTmp {
9
+ /** `<root>/.agents/local/tmp`: where a session's temporary files go, absolute. `vulcan clean` reads its age. */
10
+ static projectOf(opts: { root: string }): string {
11
+ return join(opts.root, HookConstants.PROJECT_TMP);
24
12
  }
25
13
 
26
- const folder = projectTmpOf({ root: opts.root });
14
+ /**
15
+ * Makes every Bash command of a Claude Code session run with `TMPDIR` in the project. Claude Code hands a
16
+ * SessionStart hook a file (`CLAUDE_ENV_FILE`) and sources it before each Bash command, so one `export`
17
+ * there is enough: `mktemp`, bun, node and every script a command starts then use the project folder. It
18
+ * does not move Claude Code's own task-output files or an MCP server (those need the launch file), and
19
+ * `TMPDIR` in the project's settings `env` is not applied by Claude Code, which is why this is a hook.
20
+ * Returns whether it wrote; with no file (another agent, a run outside Claude Code) it does nothing. A
21
+ * path with a line break is refused: a line of shell must never be made from a folder name.
22
+ */
23
+ static exportProjectTmp(opts: { root: string; envFile: string | undefined }): boolean {
24
+ if (opts.envFile === undefined || opts.envFile === '') {
25
+ return false;
26
+ }
27
27
 
28
- if (/[\r\n]/.test(folder)) {
29
- return false;
30
- }
28
+ const folder = ProjectTmp.projectOf({ root: opts.root });
31
29
 
32
- mkdirSync(folder, { recursive: true });
33
- appendFileSync(opts.envFile, `export TMPDIR=${shellQuote({ text: folder })}\n`);
30
+ if (/[\r\n]/.test(folder)) {
31
+ return false;
32
+ }
34
33
 
35
- return true;
36
- };
34
+ mkdirSync(folder, { recursive: true });
35
+ appendFileSync(opts.envFile, `export TMPDIR=${shellQuote({ text: folder })}\n`);
36
+
37
+ return true;
38
+ }
39
+ }