@venizia/vulcan 0.4.9 → 0.4.10-1

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.
package/README.md CHANGED
@@ -50,7 +50,7 @@ An unknown key is an error; every error names the file and the field.
50
50
 
51
51
  ## What ships (`base/`)
52
52
 
53
- - `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-01..V-C-19 (50 rules).
53
+ - `rules.md` - the base rules: write boundaries, security, process, build, and the coding style V-C-01..V-C-19 (51 rules).
54
54
  - `slots.json` - rules a project picks a wording for (V-W-01 today).
55
55
  - `skills/` - `knowledge-sync`, `docs-writing`, `docs-update`, `build-a-feature` (project-neutral; a project-specific skill stays in its project). Skill evals have not been run against a model: the skills pass the lint, and their output is a draft to review.
56
56
  - `hooks/` - `session-start.ts` (prints the rules digest) `guard-writes.ts` (asks before a database write, a migration, a deploy or a mutating HTTP call) `guard-manifest.ts` (refuses a write to the generated `.agents/vulcan.manifest.json`) `guard-package.ts` (denies a hand-written new `package.json` in a layout folder when a recorded preset has a `vulcan add` command for it, else only warns) and `guard-remote-hosts.ts` (only for a config with `remoteHosts`: asks before a command reaches a host that is not listed; whole-name or `*` match, never substring).
@@ -3,6 +3,8 @@
3
3
  * created outside the project (V-B-08). Stores a package manager, runtime or the agent tool manage
4
4
  * themselves are allowed - a default list, extended by `guard.toolOwnedPaths` in the project config.
5
5
  * `TMPDIR` or `mktemp` pointed at the system temp directory is not allowed.
6
+ * It asks by default; `guard.outside: 'deny'` in the project config refuses instead, for agents where an ask can be
7
+ * approved unseen. A write into the agent tool scratchpad is always denied.
6
8
  *
7
9
  * It guards against drift, not against an attacker, and a guard that blocks every call when its install
8
10
  * is broken costs more than it protects. So input it cannot read passes, and so does a missing package or
@@ -32,12 +34,14 @@ try {
32
34
  if (input) {
33
35
  const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
34
36
  let toolOwnedPaths: string[] = [];
37
+ let outside: string = GuardDecisions.ASK;
35
38
 
36
39
  try {
37
40
  const { ConfigLoader } = await import('../../src/config/index.ts');
38
41
  const loaded = await ConfigLoader.load({ root: projectRoot });
39
42
 
40
43
  toolOwnedPaths = loaded.ok ? loaded.config.guard.toolOwnedPaths : [];
44
+ outside = loaded.ok ? loaded.config.guard.outside : GuardDecisions.ASK;
41
45
  } catch (error) {
42
46
  console.error(
43
47
  `vulcan: the guard-outside hook could not read the project config (${error instanceof Error ? error.message : String(error)}) - the default allowlist applies`,
@@ -52,24 +56,39 @@ try {
52
56
  const places =
53
57
  'Scratch files go under .agents/local/tmp/<task>/ (worktrees under .agents/local/worktrees/, clones under .agents/local/clones/), never in /tmp or the home folder.';
54
58
 
59
+ const isDeny = isScratchpad || outside === GuardDecisions.DENY;
60
+ let reason: string[];
61
+
62
+ if (isScratchpad) {
63
+ reason = [
64
+ 'This would write into the scratchpad folder the agent tool offers (V-B-08):',
65
+ ...hitLines,
66
+ '',
67
+ `That folder is under /tmp, and V-B-08 overrides the tool line that says to use it. Nothing was written. ${places} Read a fetched file through a pipe (for example gh api ... | grep) rather than saving it.`,
68
+ ];
69
+ } else if (isDeny) {
70
+ reason = [
71
+ 'This would create files outside the project (V-B-08), and this project denies it (guard.outside):',
72
+ ...hitLines,
73
+ '',
74
+ `Nothing was written. ${places}`,
75
+ 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.',
76
+ ];
77
+ } else {
78
+ reason = [
79
+ 'This would create files outside the project (V-B-08):',
80
+ ...hitLines,
81
+ '',
82
+ `${places} Use that place, or confirm only if the owner asked for this exact path.`,
83
+ 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.',
84
+ ];
85
+ }
86
+
55
87
  console.log(
56
88
  JSON.stringify(
57
89
  HookDecision.buildTool({
58
- decision: isScratchpad ? GuardDecisions.DENY : GuardDecisions.ASK,
59
- reason: isScratchpad
60
- ? [
61
- 'This would write into the scratchpad folder the agent tool offers (V-B-08):',
62
- ...hitLines,
63
- '',
64
- `That folder is under /tmp, and V-B-08 overrides the tool line that says to use it. Nothing was written. ${places} Read a fetched file through a pipe (for example gh api ... | grep) rather than saving it.`,
65
- ]
66
- : [
67
- 'This would create files outside the project (V-B-08):',
68
- ...hitLines,
69
- '',
70
- `${places} Use that place, or confirm only if the owner asked for this exact path.`,
71
- 'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.',
72
- ],
90
+ decision: isDeny ? GuardDecisions.DENY : GuardDecisions.ASK,
91
+ reason,
73
92
  }),
74
93
  ),
75
94
  );
@@ -1,7 +1,9 @@
1
1
  /**
2
2
  * PreToolUse hook on Bash: asks before a command reaches a host the project has not listed in
3
3
  * `remoteHosts` (trusted, or readOnly for the strict read-only forms). The policy is read from the
4
- * committed manifest, `.agents/vulcan.manifest.json`, plus the personal list `remoteHosts.localFile`.
4
+ * committed manifest, `.agents/vulcan.manifest.json`, plus the personal list `remoteHosts.localFile`: one host per
5
+ * line is trusted, `readonly: <host>` is a read-only host, and a line that is not a host name or a `*` pattern is
6
+ * skipped (said once on stderr) and never trusted.
5
7
  *
6
8
  * It fails closed: Claude Code blocks a PreToolUse call only on exit 2, so every error here - a missing
7
9
  * module, a manifest without the policy - exits 2. The modules load inside the try for that reason.
@@ -34,17 +36,24 @@ try {
34
36
  const localExists = await local?.exists();
35
37
  const readingPersonal = localExists === true ? local?.text() : undefined;
36
38
  const personalText = await readingPersonal;
37
- const personal = personalText ?? '';
39
+ const personal = RemoteHosts.parsePersonalList({ text: personalText ?? '' });
38
40
  const trusted: string[] = Array.isArray(remoteHosts.trusted) ? remoteHosts.trusted : [];
39
41
  const readOnly: string[] = Array.isArray(remoteHosts.readOnly) ? remoteHosts.readOnly : [];
40
42
  const stdin = await Bun.stdin.text();
43
+
44
+ if (personal.skipped.length > 0) {
45
+ console.error(
46
+ `vulcan: the guard-remote-hosts hook skipped lines ${personal.skipped.join(', ')} of ${localFile}: not a host name or a * pattern, so they trust nothing`,
47
+ );
48
+ }
49
+
41
50
  const hookCommand = WriteGuard.parseHookCommand({ text: stdin });
42
51
  const hits = hookCommand
43
52
  ? RemoteHosts.inspectCommand({
44
53
  command: hookCommand.command,
45
54
  policy: {
46
- trusted: [...trusted, ...RemoteHosts.parseTrustedList({ text: personal })],
47
- readOnly,
55
+ trusted: [...trusted, ...personal.trusted],
56
+ readOnly: [...readOnly, ...personal.readOnly],
48
57
  ...(localFile === undefined ? {} : { localFile }),
49
58
  },
50
59
  })
package/base/rules.md CHANGED
@@ -49,6 +49,7 @@ An ID the base drops is never reused.
49
49
  | V-P-10 | **Ask once, with a recommendation.** All open decisions in one numbered round, each with a recommended answer worded so that "yes" accepts it; never ask for a fact you can look up; for a reversible choice state the default in one line and continue, only inside what V-P-02, V-P-03 and V-W-06 already allow; stop for an action they reserve, a plan awaiting approval, a change of shape, or a real fork. | SOFT |
50
50
  | V-P-11 | **Reports: answer first, in the reader's form.** Two lines before any detail; evidence as a table, not prose; a long report goes in a file and the message carries the path. The reader decides the form: the owner gets the project's report shape in their own language, with labels and form of address taken from the `owner` config and their profile, never from fixed words; another agent (a session it started, a cross-session message, a subagent) gets the plain format it asked for and nothing more. | SOFT |
51
51
  | V-P-12 | **Delegate by kind; the brief carries the rules.** Mechanical work (sweeps, greps, renames, gates, counting) goes to a smaller-model subagent; judgment stays with the main agent, which re-checks what comes back. A subagent brief carries the goal, the files, read-only by default, "no git writes", the report shape and a size under 400 words, and the rules digest reaches the subagent (through the tool's subagent-start hook where one exists, otherwise in the brief); the template is `node_modules/@venizia/vulcan/base/references/delegation-brief.md`. | SOFT - the brief; a subagent-start hook where the tool has one |
52
+ | V-P-13 | **Name the flow.** Only in a project that logs events (`events.log` on; without it the command writes a line nobody reads, so skip this rule). When you start work that belongs to a flow (`F-n`), log it, in the owner's language: `vulcan event add --kind flow --flow F-n --title "<a title the owner reads>" --why "<one line, why it exists>" --context "<2-4 sentences: what this is, what is done, what is left>" --next "<the next step and who does it>"`. Log a new one when the title, the reason, the context or the next step changes materially; the newest line wins as a whole, so repeat the fields that still hold. A board shows the title as the flow's heading, with the reason, context and next step under it; without a flow line it shows the words of its pull request or its first line, marked as having no title yet. | SOFT |
52
53
 
53
54
  ## B - Build and quality
54
55