@venizia/vulcan 0.4.10-8 → 0.4.10-9

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 (55) hide show
  1. package/README.md +1 -3
  2. package/base/claude/events.json +1 -11
  3. package/base/claude/settings.json +3 -3
  4. package/base/extensions/vulcan-guards.ts +9 -2
  5. package/base/hooks/guard-outside.ts +34 -10
  6. package/base/hooks/session-start.ts +1 -1
  7. package/base/packs/venizia.md +16 -0
  8. package/base/rules.md +23 -18
  9. package/base/templates/AGENTS.md +2 -2
  10. package/package.json +3 -3
  11. package/src/agents/atlas-block.ts +8 -31
  12. package/src/agents/generated-block.ts +52 -0
  13. package/src/agents/index.ts +2 -0
  14. package/src/agents/rules-block.ts +92 -0
  15. package/src/commands/index.ts +0 -2
  16. package/src/commands/sync.command.ts +3 -3
  17. package/src/commands/table.ts +0 -12
  18. package/src/common/constants.ts +0 -1
  19. package/src/config/schema.ts +9 -25
  20. package/src/doctor/checks.ts +110 -49
  21. package/src/doctor/common/constants.ts +0 -2
  22. package/src/events/common/constants.ts +2 -12
  23. package/src/events/hook.ts +5 -56
  24. package/src/hooks/command-view.ts +1 -1
  25. package/src/hooks/common/types.ts +2 -0
  26. package/src/hooks/guard-git.ts +40 -0
  27. package/src/hooks/guard-outside.ts +52 -2
  28. package/src/hooks/session-digest.ts +24 -123
  29. package/src/hooks/shell-folders.ts +127 -2
  30. package/src/hooks/shell-writes.ts +4 -0
  31. package/src/hooks/shell.ts +111 -2
  32. package/src/manifest/render.ts +3 -15
  33. package/src/rules/base.ts +11 -7
  34. package/src/rules/index.ts +1 -0
  35. package/src/rules/packs.ts +44 -0
  36. package/src/sync/agents-block.ts +94 -0
  37. package/src/sync/base-rules.ts +3 -3
  38. package/src/sync/index.ts +1 -1
  39. package/src/visualize/architecture.ts +504 -0
  40. package/src/visualize/assets.ts +15 -14
  41. package/src/visualize/compare-render.ts +22 -24
  42. package/src/visualize/constants.ts +15 -0
  43. package/src/visualize/diagrams.ts +13 -121
  44. package/src/visualize/kinds-render.ts +2 -2
  45. package/src/visualize/labels-vi.ts +14 -0
  46. package/src/visualize/labels.ts +2 -0
  47. package/src/visualize/layout.ts +409 -66
  48. package/src/visualize/page.ts +34 -10
  49. package/src/visualize/schema.ts +18 -0
  50. package/src/visualize/sections.ts +22 -9
  51. package/base/hooks/guard-manifest.ts +0 -2
  52. package/base/hooks/guard-package.ts +0 -2
  53. package/base/hooks/guard-remote-hosts.ts +0 -2
  54. package/src/commands/graph.command.ts +0 -6
  55. package/src/sync/atlas-block.ts +0 -56
@@ -280,18 +280,6 @@ export class CommandTable {
280
280
  exits:
281
281
  '0 on success; 1 when --stable and --nightly are both given, the dist-tags cannot be read, or the install or sync fails.',
282
282
  },
283
- [VulcanCommands.GRAPH]: {
284
- help: ` graph build [--full] Write the code graph of the project (vulcan x atlas graph build)
285
- graph status [--json] Say whether the graph still matches the files it was built from`,
286
- flags: {
287
- '--full': 'build: read everything again, whatever changed',
288
- '--json': 'status: print the answer as one line of JSON',
289
- },
290
- positionals: 1,
291
- unknownExit: ExitCodes.USAGE,
292
- exits:
293
- '0 on success, and for every state of status (fresh, behind, diverged, unknown); 1 when the graph cannot be built (no git repository, a bad package.json) or atlas is not installed; 2 for an argument it does not know',
294
- },
295
283
  [VulcanCommands.X]: {
296
284
  help: ` x <tool> [args...] Run a shipped tool at the pinned version: okf, atlas`,
297
285
  passthrough: true,
@@ -16,7 +16,6 @@ export class VulcanCommands {
16
16
  static readonly CI = 'ci';
17
17
  static readonly BOARD = 'board';
18
18
  static readonly EVENT = 'event';
19
- static readonly GRAPH = 'graph';
20
19
  static readonly X = 'x';
21
20
  static readonly HELP = 'help';
22
21
  static readonly VERSION = 'version';
@@ -3,6 +3,7 @@ import { LayoutFolder } from '../common/layout-folder.ts';
3
3
  import { DOCTOR_SCHEMA } from '../doctor/schema.ts';
4
4
  import { GuardDecisions } from '../hooks/common/constants.ts';
5
5
  import { OWNER_SCHEMA } from '../owner/schema.ts';
6
+ import { RulePacks } from '../rules/packs.ts';
6
7
  import { AgentSignaturePolicies } from '../commit/common/index.ts';
7
8
  import type { TAgentSignaturePolicy } from '../commit/common/index.ts';
8
9
  import { SubjectShape } from '../commit/subject.ts';
@@ -69,18 +70,6 @@ const PUSH_TARGET = z
69
70
  .string()
70
71
  .regex(/^[A-Za-z0-9._/*-]+$/, { message: 'a branch name, with * for any run of characters' });
71
72
 
72
- /** An import prefix: the start of a specifier, ending in a slash (`@/`, `~/`). */
73
- const GRAPH_ALIAS_PREFIX = z
74
- .string()
75
- .regex(/^[^\s]+\/$/, 'an alias prefix ends with a slash, for example "@/"');
76
- /** The folder an alias leads to, from the importing package: relative to the package, never climbing. */
77
- const GRAPH_ALIAS_FOLDER = z
78
- .string()
79
- .refine(
80
- (value) => !value.startsWith('/') && !value.split('/').includes('..'),
81
- 'a folder of the package, from its root',
82
- );
83
-
84
73
  /** A key that was removed: optional, and refused when present with the key and what to do, instead of a bare "unrecognized key". */
85
74
  const REMOVED_OKF_KEY = (opts: { fix: string }) =>
86
75
  z
@@ -238,6 +227,14 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
238
227
  agents: z.array(CODING_AGENT).optional(),
239
228
  /** Choice of each base rule slot, keyed by rule ID (for example `V-W-01`) to the option picked; default `{}`. */
240
229
  rules: z.record(z.string().regex(ConfigConstants.RULE_ID_PATTERN), z.string()).default({}),
230
+ /** The shipped rule packs this project follows, by name (`venizia`): rules for one stack, outside the base rules every project gets. */
231
+ packs: z
232
+ .array(
233
+ z.string().refine((name) => RulePacks.names().includes(name), {
234
+ error: () => `a rule pack VULCAN ships: ${RulePacks.names().join(', ')}`,
235
+ }),
236
+ )
237
+ .default([]),
241
238
  /** The folders `vulcan init` and `add` put apps in, as the user named them. */
242
239
  layout: z
243
240
  .strictObject({
@@ -703,19 +700,6 @@ export const VULCAN_CONFIG_SCHEMA = z.strictObject({
703
700
  maxAgeDays: z.number().int().min(1).optional(),
704
701
  })
705
702
  .default({ log: false }),
706
- /**
707
- * How `vulcan x atlas graph build` reads the code. `exclude` is globs of tracked files left out; `aliases` maps an import
708
- * prefix to a folder of the importing package (`{ '@/': 'src/' }`), so `@/x` in `packages/a/src/y.ts` leads to
709
- * `packages/a/src/x`. An alias not listed is counted as an external import.
710
- */
711
- graph: z
712
- .strictObject({
713
- /** Globs of tracked files, from the project root, the graph leaves out. */
714
- exclude: z.array(z.string().min(1)).default([]),
715
- /** An import prefix ending in a slash, mapped to a folder of the importing package. */
716
- aliases: z.record(GRAPH_ALIAS_PREFIX, GRAPH_ALIAS_FOLDER).default({}),
717
- })
718
- .default({ exclude: [], aliases: {} }),
719
703
  /**
720
704
  * What `vulcan` keeps tidy in `.agents/local/` by itself. `autoClean` (default true) lets the session-start hook, at
721
705
  * most once a day, remove the safe part: stale `tmp/`, browser leftovers older than an hour, event files past their
@@ -8,21 +8,27 @@ import { MCP_SERVER_HINT, ProjectScaffold } from '../init/index.ts';
8
8
  import { ProjectPackages } from '../config/index.ts';
9
9
  import { ProjectKey } from '../events/project-key.ts';
10
10
  import type { TResolvedConfig } from '../config/index.ts';
11
- import { BaseRules, RuleParser, RuleSlots } from '../rules/index.ts';
11
+ import { BaseRules, RulePacks, RuleParser, RuleSlots } from '../rules/index.ts';
12
12
  import { ManifestConstants, ProjectManifest } from '../manifest/index.ts';
13
13
  import { AgentScopes, AgentSelection, AgentTable, LocalChoice } from '../agents/index.ts';
14
14
  import { CommitHook, CommitHookStates } from '../commit/index.ts';
15
15
  import { EventConstants } from '../events/common/index.ts';
16
16
  import { EventRetention } from '../events/retention.ts';
17
17
  import { EventSettings } from '../events/settings.ts';
18
- import { AgentFiles, AtlasBlockPlan, LocalPlan, SyncPlanner, SyncStatuses } from '../sync/index.ts';
18
+ import {
19
+ AgentFiles,
20
+ AgentsBlockPlan,
21
+ LocalPlan,
22
+ SyncPlanner,
23
+ SyncStatuses,
24
+ } from '../sync/index.ts';
19
25
  import { BrowserSocket, LocalFormat, LocalScan, LocalStates } from '../local/index.ts';
20
26
  import { CLAUDE_LAUNCH_FILE } from '../sync/claude-launch.ts';
21
27
  import { PrivateValues } from './private-values.ts';
22
28
  import { ReplySwitch, OwnerConstants, OwnerReplySwitch, OwnerProfile } from '../owner/index.ts';
23
29
  import { SkillCatalog } from '@venizia/vulcan-atlas';
24
30
  import { HookConstants, ProjectTmp } from '../hooks/index.ts';
25
- import { DoctorChecks, DoctorConstants } from './common/index.ts';
31
+ import { DoctorChecks, DoctorConstants, PrivateValueKinds } from './common/index.ts';
26
32
  import type { IViolation, TDoctorCheck } from './common/index.ts';
27
33
  import { Makefile } from './makefile.ts';
28
34
 
@@ -190,19 +196,24 @@ export class ProjectContract {
190
196
  * rules points at a base rule - one the base does not carry dangles.
191
197
  */
192
198
  static checkRuleIds(opts: ICheckContext): IViolation[] {
193
- const base = BaseRules.read();
199
+ const base = BaseRules.read({ packs: opts.config.packs });
194
200
 
195
201
  return RuleParser.parseBaseReferences({
196
202
  markdown: readText({ file: join(opts.root, '.agents', 'rules.md') }),
197
203
  })
198
204
  .filter((id) => base[id] === undefined)
199
- .map((id) =>
200
- createViolation({
205
+ .map((id) => {
206
+ const pack = RulePacks.holderOf({ id });
207
+
208
+ return createViolation({
201
209
  check: DoctorChecks.RULE_IDS,
202
210
  file: '.agents/rules.md',
203
- message: `${id} is not a base rule - give the extension a bare ID`,
204
- }),
205
- );
211
+ message:
212
+ pack === undefined
213
+ ? `${id} is not a base rule - give the extension a bare ID`
214
+ : `${id} is in the ${pack} pack - add '${pack}' to packs in the config`,
215
+ });
216
+ });
206
217
  }
207
218
 
208
219
  static checkRuleSlots(opts: ICheckContext): IViolation[] {
@@ -896,9 +907,9 @@ export class ProjectContract {
896
907
  return warnings;
897
908
  }
898
909
 
899
- /** Info only: the Atlas block of AGENTS.md is missing or no longer matches the config. */
910
+ /** Info only: the Atlas or rules block of AGENTS.md is missing or no longer matches the config. */
900
911
  static checkAtlasBlock(opts: ICheckContext): IViolation[] {
901
- const merged = AtlasBlockPlan.merged({ root: opts.root, config: opts.config });
912
+ const merged = AgentsBlockPlan.merged({ root: opts.root, config: opts.config });
902
913
 
903
914
  return merged === undefined || !merged.changed
904
915
  ? []
@@ -906,7 +917,7 @@ export class ProjectContract {
906
917
  createViolation({
907
918
  check: DoctorChecks.AGENTS,
908
919
  file: 'AGENTS.md',
909
- message: `the Atlas block is missing or out of date - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
920
+ message: `the Atlas or rules block of AGENTS.md is missing or out of date - run '${ProjectLayout.VULCAN_COMMAND} sync'`,
910
921
  }),
911
922
  ];
912
923
  }
@@ -987,38 +998,66 @@ export class ProjectContract {
987
998
  }
988
999
 
989
1000
  /**
990
- * Something directly under `.agents/local/` that is not a folder of the layout, a file VULCAN writes, or a
991
- * browser's scratch folder. Nothing removes it; the message says where scratch belongs. A warning.
1001
+ * What is directly under `.agents/local/` and is not a folder of the layout, a file VULCAN writes, or a browser's
1002
+ * scratch folder, in one warning: how many, how big, and their names. Nothing removes them.
992
1003
  */
993
1004
  static checkUnknownLocal(opts: ICheckContext): IViolation[] {
994
- return LocalScan.unknown({ root: opts.root }).map((entry) =>
995
- createViolation({
996
- check: DoctorChecks.LOCAL,
997
- file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.name}`,
998
- message: `not an entry VULCAN knows (${LocalFormat.formatBytes({ bytes: entry.bytes })}): put scratch in tmp/ and what you want to keep in reports/, what one agent keeps for itself in agents/<name>/; a script the team relies on belongs in the tracked tree (scripts/), where it gets review and history; nothing removes it`,
999
- }),
1000
- );
1005
+ const unknown = LocalScan.unknown({ root: opts.root });
1006
+
1007
+ return unknown.length === 0
1008
+ ? []
1009
+ : [
1010
+ createViolation({
1011
+ check: DoctorChecks.LOCAL,
1012
+ file: ProjectLayout.LOCAL_DIRECTORY,
1013
+ message: `${unknown.length} ${unknown.length === 1 ? 'entry is' : 'entries are'} not ${unknown.length === 1 ? 'one' : 'ones'} VULCAN knows: ${unknown
1014
+ .slice(0, 10)
1015
+ .map((entry) => `${entry.name} (${LocalFormat.formatBytes({ bytes: entry.bytes })})`)
1016
+ .join(
1017
+ ', ',
1018
+ )}${unknown.length > 10 ? `, and ${unknown.length - 10} more` : ''}; put scratch in tmp/ and what you want to keep in reports/, what one agent keeps for itself in agents/<name>/; a script the team relies on belongs in the tracked tree (scripts/), where it gets review and history; nothing removes ${unknown.length === 1 ? 'it' : 'them'}`,
1019
+ }),
1020
+ ];
1001
1021
  }
1002
1022
 
1003
- /** What an agent left under `.agents/local/` that has outlived its use, one line each with the command that clears it. */
1023
+ /**
1024
+ * What an agent left under `.agents/local/` that has outlived its use, in one warning: how many in each scope, how
1025
+ * big, and the command that clears them (which, without `--yes`, lists each one).
1026
+ */
1004
1027
  static checkStaleLocal(opts: ICheckContext): IViolation[] {
1005
- return LocalScan.scan({ root: opts.root })
1006
- .filter((entry) =>
1007
- [
1008
- LocalStates.STALE,
1009
- LocalStates.MERGED,
1010
- LocalStates.GONE,
1011
- LocalStates.ORPHAN,
1012
- LocalStates.SHIPPED,
1013
- ].includes(entry.state),
1014
- )
1015
- .map((entry) =>
1016
- createViolation({
1017
- check: DoctorChecks.LOCAL,
1018
- file: `${ProjectLayout.LOCAL_DIRECTORY}/${entry.where}`,
1019
- message: `${entry.state === LocalStates.STALE && entry.note === '' ? `left ${LocalFormat.formatAge({ ageMs: entry.ageMs })} ago` : entry.note} (${LocalFormat.formatBytes({ bytes: entry.bytes })}) - run: vulcan clean --${entry.scope} --yes`,
1020
- }),
1021
- );
1028
+ const stale = LocalScan.scan({ root: opts.root }).filter((entry) =>
1029
+ [
1030
+ LocalStates.STALE,
1031
+ LocalStates.MERGED,
1032
+ LocalStates.GONE,
1033
+ LocalStates.ORPHAN,
1034
+ LocalStates.SHIPPED,
1035
+ ].includes(entry.state),
1036
+ );
1037
+
1038
+ if (stale.length === 0) {
1039
+ return [];
1040
+ }
1041
+
1042
+ const scopes = [...new Set(stale.map((entry) => entry.scope))];
1043
+ const counts = new Map<string, number>();
1044
+
1045
+ for (const entry of stale) {
1046
+ const group = `${entry.state} in ${entry.scope}`;
1047
+
1048
+ counts.set(group, (counts.get(group) ?? 0) + 1);
1049
+ }
1050
+
1051
+ const groups = [...counts.entries()];
1052
+ const bytes = stale.reduce((total, entry) => total + entry.bytes, 0);
1053
+
1054
+ return [
1055
+ createViolation({
1056
+ check: DoctorChecks.LOCAL,
1057
+ file: ProjectLayout.LOCAL_DIRECTORY,
1058
+ message: `${stale.length} ${stale.length === 1 ? 'entry has' : 'entries have'} outlived ${stale.length === 1 ? 'its' : 'their'} use (${LocalFormat.formatBytes({ bytes })}): ${groups.map(([group, count]) => `${count} ${group}`).join(', ')}; run: vulcan clean ${scopes.map((scope) => `--${scope}`).join(' ')} --yes (without --yes it lists each one)`,
1059
+ }),
1060
+ ];
1022
1061
  }
1023
1062
 
1024
1063
  /** The owner cards are off for this shell (`VULCAN_OWNER_REPLY=off`): a session an agent starts sets it, an owner who exported it by mistake sees why the rules carry no shape card; a note, never a failure. */
@@ -1152,24 +1191,46 @@ export class ProjectContract {
1152
1191
  });
1153
1192
  }
1154
1193
 
1155
- /** Private values in committed files: one warning per file with the kinds and counts, never the text, and one per acknowledgment that covered nothing. */
1194
+ /**
1195
+ * Private values in committed files, never the text: one warning per file that holds a key, a token or a URL
1196
+ * credential, with the kinds and counts; the files that hold only addresses or machine paths (an example IP in a
1197
+ * policy file, a path in a doc) in one warning; and one per acknowledgment that covered nothing.
1198
+ */
1156
1199
  static checkPrivateValues(opts: ICheckContext): IViolation[] {
1157
1200
  const { findings, unmatched } = PrivateValues.scan({
1158
1201
  root: opts.root,
1159
1202
  acknowledged: opts.config.doctor.privateValues.acknowledged,
1160
1203
  });
1161
1204
  const where = 'doctor.privateValues.acknowledged';
1205
+ const kindsOf = (counts: Record<string, number | undefined>): string =>
1206
+ Object.entries(counts)
1207
+ .map(([kind, count]) => `${count} ${kind}`)
1208
+ .join(', ');
1209
+ const isMild = (finding: { counts: Record<string, number | undefined> }): boolean =>
1210
+ Object.keys(finding.counts).every((kind) =>
1211
+ [PrivateValueKinds.IPV4, PrivateValueKinds.MACHINE_PATH].includes(kind),
1212
+ );
1213
+ const mild = findings.filter((finding) => isMild(finding));
1162
1214
 
1163
1215
  return [
1164
- ...findings.map((finding) =>
1165
- createViolation({
1166
- check: DoctorChecks.PRIVATE_VALUES,
1167
- file: finding.file,
1168
- message: `holds private values: ${Object.entries(finding.counts)
1169
- .map(([kind, count]) => `${count} ${kind}`)
1170
- .join(', ')} (not shown); remove them, or record the decision in ${where}`,
1171
- }),
1172
- ),
1216
+ ...findings
1217
+ .filter((finding) => !isMild(finding))
1218
+ .map((finding) =>
1219
+ createViolation({
1220
+ check: DoctorChecks.PRIVATE_VALUES,
1221
+ file: finding.file,
1222
+ message: `holds private values: ${kindsOf(finding.counts)} (not shown); remove them, or record the decision in ${where}`,
1223
+ }),
1224
+ ),
1225
+ ...(mild.length === 0
1226
+ ? []
1227
+ : [
1228
+ createViolation({
1229
+ check: DoctorChecks.PRIVATE_VALUES,
1230
+ file: mild.length === 1 ? mild[0].file : `${mild.length} files`,
1231
+ message: `${mild.length === 1 ? 'holds' : `${mild.length} files hold`} only addresses or machine paths: ${mild.map((finding) => `${finding.file} (${kindsOf(finding.counts)})`).join(', ')} (not shown); remove them, or record the decision in ${where}`,
1232
+ }),
1233
+ ]),
1173
1234
  ...unmatched.map((entry) =>
1174
1235
  createViolation({
1175
1236
  check: DoctorChecks.PRIVATE_VALUES,
@@ -35,8 +35,6 @@ export class DoctorChecks {
35
35
  static readonly LOCAL = 'local';
36
36
  /** The personal profile file: unreadable, not gitignored or tracked by git; a warning. */
37
37
  static readonly PROFILE = 'profile';
38
- /** Guard config: a trusted script is a note; a stale one is a warning. */
39
- static readonly GUARDS = 'guards';
40
38
  /** The clone commit-msg hook when a commit check is on: missing, stale or not calling commit-check; a warning. */
41
39
  static readonly COMMIT_HOOK = 'commit-hook';
42
40
  /** The events.dir folder when outside the project: missing, not a folder or not writable; a warning. */
@@ -3,6 +3,7 @@ import { EventActorNames } from './actor-names.ts';
3
3
  /** What happened. A board reads these; add one only when a reader needs to tell it apart. */
4
4
  export class EventKinds {
5
5
  static readonly SESSION_START = 'session-start';
6
+ /** No longer written (a turn that ends is not an event); read so a log written before still folds until its retention removes it. */
6
7
  static readonly SESSION_STOP = 'session-stop';
7
8
  static readonly MSG_SENT = 'msg-sent';
8
9
  static readonly MSG_RECEIVED = 'msg-received';
@@ -16,7 +17,7 @@ export class EventKinds {
16
17
  static readonly FLOW = 'flow';
17
18
  /** Something was put live; a milestone of its flow, like a merge. Its summary says what. */
18
19
  static readonly DEPLOY = 'deploy';
19
- /** An agent used a tool, at most once in `EventConstants.TICK_SECONDS` per session: the board reads it as working. */
20
+ /** No longer written (a tool that is used is not an event); read so a log written before still folds until its retention removes it. */
20
21
  static readonly TOOL_TICK = 'tool-tick';
21
22
 
22
23
  static readonly SCHEME_SET = new Set<string>([
@@ -112,7 +113,6 @@ export class EventFlags {
112
113
  /** The names a Claude Code hook payload carries, as Claude Code 2.1.317 sends them. */
113
114
  export class ClaudeHookEvents {
114
115
  static readonly SESSION_START = 'SessionStart';
115
- static readonly STOP = 'Stop';
116
116
  static readonly SUBAGENT_STOP = 'SubagentStop';
117
117
  static readonly NOTIFICATION = 'Notification';
118
118
  static readonly POST_TOOL_USE = 'PostToolUse';
@@ -152,16 +152,6 @@ export class EventConstants {
152
152
  static readonly CONTEXT_MAX = 600;
153
153
  /** What a sent message is called when its sender gave no label: the text of a message is never used. */
154
154
  static readonly MESSAGE_SENT_LABEL = 'message sent';
155
- /** The summary of a tool tick: it says that a tool was used, and nothing of which. */
156
- static readonly TOOL_TICK_LABEL = 'using a tool';
157
- /** A session writes at most one tool tick in each window of this many seconds. */
158
- static readonly TICK_SECONDS = 30;
159
- /**
160
- * The folder, from the project root, that holds one empty stamp per session and window, `<session>.<window>`; a tick
161
- * removes the stamps of earlier windows. Spelt out because the hook imports no other module of the package (a test holds it
162
- * inside `ProjectLayout.LOCAL_DIRECTORY/tmp`).
163
- */
164
- static readonly TICK_FOLDER = '.agents/local/tmp/event-ticks';
165
155
  static readonly REF_MAX = 120;
166
156
  /** A flow line's lists: how many items, and how long one is. */
167
157
  static readonly ITEM_COUNT_MAX = 30;
@@ -1,5 +1,3 @@
1
- import { mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
2
- import { join } from 'node:path';
3
1
  import { RecordValue } from '../common/record.ts';
4
2
  import { ClaudeHookEvents, EventConstants, EventKinds, EventSources } from './common/index.ts';
5
3
  import type { IEvent, IHookEvent } from './common/index.ts';
@@ -16,10 +14,10 @@ const text = (opts: { value: unknown }): string =>
16
14
  export class EventHook {
17
15
  /**
18
16
  * The event a payload stands for, or `undefined` when the payload is not one to log. Only these fields are
19
- * read: `source` and `model` of a session start, `stop_hook_active` of a stop, `agent_type` and `agent_id` of a
20
- * subagent stop, `notification_type` and `title` of a notification, and `to` and `summary` of a SendMessage
21
- * call (its first line, only when the sender gave no summary). A tool tick reads nothing but the event's name.
22
- * `last_assistant_message`, `message`, `tool_response`, `tool_input` and every command stay unread.
17
+ * read: `source` and `model` of a session start, `agent_type` and `agent_id` of a subagent stop,
18
+ * `notification_type` and `title` of a notification, and `to` and `summary` of a SendMessage call (the label the
19
+ * sender gave it, or a fixed one). A turn that ends and a tool that is used are not events.
20
+ * `last_assistant_message`, the text of a message, `tool_response`, `tool_input` and every command stay unread.
23
21
  */
24
22
  static map(opts: { input: unknown }): IHookEvent | undefined {
25
23
  const { input } = opts;
@@ -39,12 +37,6 @@ export class EventHook {
39
37
  };
40
38
  }
41
39
 
42
- case ClaudeHookEvents.STOP: {
43
- return input.stop_hook_active === true
44
- ? undefined
45
- : { kind: EventKinds.SESSION_STOP, summary: 'turn ended' };
46
- }
47
-
48
40
  case ClaudeHookEvents.SUBAGENT_STOP: {
49
41
  return {
50
42
  kind: EventKinds.SUBAGENT_STOP,
@@ -67,9 +59,7 @@ export class EventHook {
67
59
  }
68
60
 
69
61
  case ClaudeHookEvents.POST_TOOL_USE: {
70
- return input.tool_name === ClaudeHookEvents.SEND_MESSAGE_TOOL
71
- ? EventHook.mapSend({ input })
72
- : { kind: EventKinds.TOOL_TICK, summary: EventConstants.TOOL_TICK_LABEL };
62
+ return EventHook.mapSend({ input });
73
63
  }
74
64
 
75
65
  default: {
@@ -125,36 +115,6 @@ export class EventHook {
125
115
  };
126
116
  }
127
117
 
128
- /**
129
- * Whether this session may write a tick now: the first call of each window creates the window's stamp and wins; a
130
- * call that finds the stamp already there loses. `wx` makes that one step, so calls at the same instant cannot both win.
131
- */
132
- private static takeTick(opts: { root: string; session: string; now: number }): boolean {
133
- const folder = join(opts.root, EventConstants.TICK_FOLDER);
134
- const window = Math.floor(opts.now / (EventConstants.TICK_SECONDS * 1000));
135
- const stamp = join(folder, `${opts.session.replace(/[^\w-]/g, '_') || 'session'}.${window}`);
136
-
137
- mkdirSync(folder, { recursive: true });
138
-
139
- try {
140
- writeFileSync(stamp, '', { flag: 'wx' });
141
- } catch (error) {
142
- if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
143
- return false;
144
- }
145
-
146
- throw error;
147
- }
148
-
149
- for (const name of readdirSync(folder)) {
150
- if (Number(name.slice(name.lastIndexOf('.') + 1)) < window) {
151
- rmSync(join(folder, name), { force: true });
152
- }
153
- }
154
-
155
- return true;
156
- }
157
-
158
118
  /**
159
119
  * Logs what a payload stands for, when the manifest says the log is on. Returns the line it wrote.
160
120
  * `root` is the project, where the manifest is; the flow comes from the message, else the branch at the
@@ -178,17 +138,6 @@ export class EventHook {
178
138
  return undefined;
179
139
  }
180
140
 
181
- if (
182
- mapped.kind === EventKinds.TOOL_TICK &&
183
- !EventHook.takeTick({
184
- root: opts.root,
185
- session: text({ value: opts.input.session_id }),
186
- now: opts.now ?? Date.now(),
187
- })
188
- ) {
189
- return undefined;
190
- }
191
-
192
141
  const cwd = text({ value: opts.input.cwd }) || opts.root;
193
142
  const flowId =
194
143
  (mapped.flowText === undefined ? undefined : EventFlow.fromText({ text: mapped.flowText })) ??
@@ -40,7 +40,7 @@ const GH_REQUESTS = new Set(['api', 'secret', 'variable']);
40
40
  const GH_REPOSITORY_FLAGS = new Set(['-R', '--repo']);
41
41
 
42
42
  /** `find` runs a command only with these; without them it only lists. */
43
- const FIND_RUNS = new Set(['-exec', '-execdir', '-ok', '-okdir', '-delete']);
43
+ const FIND_RUNS = new Set([...ShellPrograms.FIND_RUN_OPTIONS, '-delete']);
44
44
 
45
45
  /** Programs that read their heredoc as a query or a script: the body is part of what they run. */
46
46
  const HEREDOC_READERS = new Set([
@@ -48,4 +48,6 @@ export interface IOutsideHit {
48
48
  message: string;
49
49
  /** Whether the path is under the scratchpad folder an agent tool offers: the hook denies it, it does not ask. */
50
50
  isAgentToolScratchpad: boolean;
51
+ /** Whether the check could not read the line or the target, so it does not know that anything is outside: the hook asks, even where the project denies. */
52
+ isUnread: boolean;
51
53
  }
@@ -289,6 +289,45 @@ const ghCall = (opts: { args: string[] }): { group: string; action: string; rest
289
289
  return { group: names[0] ?? '', action: names[1] ?? '', rest: opts.args.slice(index) };
290
290
  };
291
291
 
292
+ const REF_ENDPOINT = /^repos\/[^/]+\/[^/]+\/git\/refs\/heads\/(.+)$/;
293
+
294
+ /** The path `gh api` calls for a word: without the host, a `?query`, the slashes at its ends, decoded once. */
295
+ const endpointOf = (opts: { word: string }): string => {
296
+ const path = opts.word
297
+ .replace(/^https?:\/\/api\.github\.com/i, '')
298
+ .replace(/[?#].*$/s, '')
299
+ .replace(/^\/+|\/+$/g, '');
300
+
301
+ try {
302
+ return decodeURIComponent(path);
303
+ } catch {
304
+ return path;
305
+ }
306
+ };
307
+
308
+ /** `gh api -X DELETE repos/<owner>/<repo>/git/refs/heads/<branch>` deletes the branch as `git push --delete` does. */
309
+ const inspectGhApi = (opts: { args: string[] }): IGitHit[] => {
310
+ const { args } = opts;
311
+ const isDelete = args.some(
312
+ (word, index) =>
313
+ /^(-X|--method)=?DELETE$/i.test(word) ||
314
+ (/^(-X|--method)$/.test(word) && (args[index + 1] ?? '').toUpperCase() === 'DELETE'),
315
+ );
316
+
317
+ if (ghCall({ args }).group !== 'api' || !isDelete) {
318
+ return [];
319
+ }
320
+
321
+ return args
322
+ .map((word) => REF_ENDPOINT.exec(endpointOf({ word }))?.[1])
323
+ .filter((name): name is string => name !== undefined && isProtected({ name }))
324
+ .map((name) => ({
325
+ decision: GuardDecisions.DENY,
326
+ rule: 'V-W-06',
327
+ message: `deleting the remote branch '${name}'`,
328
+ }));
329
+ };
330
+
292
331
  /** `gh pr merge [<pr>] --delete-branch`: the PR's head branch decides, and `gh` is asked for it. */
293
332
  const inspectGhMerge = (opts: {
294
333
  args: string[];
@@ -385,6 +424,7 @@ const inspectOne = (opts: {
385
424
  return [
386
425
  ...inspectGhMerge({ args: program.args, cwd: opts.cwd, run: opts.run }),
387
426
  ...inspectGhCreate({ args: program.args }),
427
+ ...inspectGhApi({ args: program.args }),
388
428
  ];
389
429
  }
390
430
 
@@ -163,6 +163,7 @@ export class OutsideGuard {
163
163
  }
164
164
 
165
165
  let unread: string | undefined;
166
+ let assigned = new Set<string>();
166
167
 
167
168
  if (opts.input.command !== undefined) {
168
169
  const parsed = ShellParser.parseChecked({ command: opts.input.command });
@@ -175,6 +176,7 @@ export class OutsideGuard {
175
176
  });
176
177
 
177
178
  unread = ShellUnread.reasonOf(parsed);
179
+ assigned = ShellFolders.assignedNames({ commands: parsed.commands });
178
180
 
179
181
  // A command's own redirects open in the folder it starts in, a `cd`'s included.
180
182
  for (const [index, command] of parsed.commands.entries()) {
@@ -188,6 +190,8 @@ export class OutsideGuard {
188
190
  ...ShellWrites.targetsOf({ command, base: folder.base, tmp }).map((target) => ({
189
191
  ...target,
190
192
  pwd: folder.pwd,
193
+ vars: folder.vars,
194
+ isKnown: folder.isKnown,
191
195
  })),
192
196
  );
193
197
  }
@@ -197,18 +201,61 @@ export class OutsideGuard {
197
201
  const hits: IOutsideHit[] =
198
202
  unread === undefined
199
203
  ? []
200
- : [{ path: '(the command line)', message: unread, isAgentToolScratchpad: false }];
204
+ : [
205
+ {
206
+ path: '(the command line)',
207
+ message: unread,
208
+ isAgentToolScratchpad: false,
209
+ isUnread: true,
210
+ },
211
+ ];
201
212
 
202
213
  for (const target of targets) {
203
- const expanded = ShellFolders.expandPath({ word: target.word, home, env, cwd: target.pwd });
214
+ const expanded = ShellFolders.expandPath({
215
+ word: target.word,
216
+ home,
217
+ env: { ...env, ...target.vars },
218
+ cwd: target.pwd,
219
+ });
204
220
 
205
221
  if (expanded === undefined) {
222
+ // Part of the word is unknown, but the folder in front of it may not be: that folder decides.
223
+ const lands = ShellFolders.folderOfUnknown({
224
+ word: target.word,
225
+ home,
226
+ env: { ...env, ...target.vars },
227
+ cwd: target.pwd,
228
+ base: target.base,
229
+ isKnown: target.isKnown ?? true,
230
+ assigned,
231
+ });
232
+ const folder = lands === undefined ? undefined : realOf({ path: lands });
233
+
234
+ if (
235
+ folder !== undefined &&
236
+ !isInside({ path: folder, root }) &&
237
+ !matchesAny({ path: `${folder}/x`, patterns })
238
+ ) {
239
+ hits.push({
240
+ path: folder,
241
+ message: `${target.message}: it lands in ${folder}, outside the project, whatever the expansion is`,
242
+ isAgentToolScratchpad: matchesAny({
243
+ path: folder,
244
+ patterns: HookConstants.AGENT_TOOL_SCRATCHPAD_PATTERNS,
245
+ }),
246
+ isUnread: false,
247
+ });
248
+
249
+ continue;
250
+ }
251
+
206
252
  // A redirect to a word that cannot be worked out (`> $f`, `&>$fd`, `>&$fd`) may write a file outside the project.
207
253
  if (target.isAmbiguous === true || target.isRedirect === true) {
208
254
  hits.push({
209
255
  path: target.word,
210
256
  message: `${target.message}: the target has an expansion this check cannot work out`,
211
257
  isAgentToolScratchpad: false,
258
+ isUnread: true,
212
259
  });
213
260
  }
214
261
 
@@ -223,6 +270,7 @@ export class OutsideGuard {
223
270
  path: written,
224
271
  message: `${target.message}: a path under /proc or /dev/fd names a process, which this check cannot follow`,
225
272
  isAgentToolScratchpad: false,
273
+ isUnread: true,
226
274
  });
227
275
 
228
276
  continue;
@@ -236,6 +284,7 @@ export class OutsideGuard {
236
284
  path: written,
237
285
  message: `${target.message}: the path goes through more links than the system follows`,
238
286
  isAgentToolScratchpad: false,
287
+ isUnread: true,
239
288
  });
240
289
 
241
290
  continue;
@@ -249,6 +298,7 @@ export class OutsideGuard {
249
298
  path,
250
299
  patterns: HookConstants.AGENT_TOOL_SCRATCHPAD_PATTERNS,
251
300
  }),
301
+ isUnread: false,
252
302
  });
253
303
  }
254
304
  }