@zgeoff/skill-gate 0.2.2 → 0.2.4

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
@@ -1,10 +1,10 @@
1
1
  # @zgeoff/skill-gate
2
2
 
3
- The skill gate is a Claude Code `PreToolUse` hook that denies an edit until the session has loaded
4
- every skill the path needs, and names the missing skills. It also warns when a Bash command writes a
5
- gated path through a redirect, `tee`, `sed -i`, `cp`, `mv` or an inline script. The warning names
6
- the skills to load and the edit tools, and the command still runs. The package holds no rules: each
7
- repo keeps its own in `.claude/skill-gate.json`, and a repo without that file has no gate.
3
+ The skill gate is a Claude Code hook that denies an edit until the session has loaded every skill
4
+ the path needs, and names the missing skills. After a Bash command, it compares `git status` with
5
+ the status before the command, and it blocks when the command changed a gated file that the session
6
+ lacks the skills for. The package holds no rules: each repo keeps its own in
7
+ `.claude/skill-gate.json`, and a repo without that file has no gate.
8
8
 
9
9
  ## Install
10
10
 
@@ -16,18 +16,17 @@ Install it at the repo root, so that Bun resolves it from `.claude/hooks/`. The
16
16
 
17
17
  ## Entry point
18
18
 
19
- The hook runs a file in the repo that calls the package, at
20
- `.claude/hooks/skill-gate/skill-gate.ts`:
19
+ The hook runs a file in the repo that calls the package's `runSkillGate`, at
20
+ `.claude/hooks/skill-gate/skill-gate.ts`. The `hook-skill-gate` entry of repo-sync delivers this
21
+ file from zgeoff/tools. `runSkillGate` reads the hook payload from stdin, prints the hook output,
22
+ and exits the process.
21
23
 
22
- ```ts
23
- import { runSkillGate } from '@zgeoff/skill-gate';
24
+ The entry point fails closed. When the package cannot load, the entry point blocks each edit that a
25
+ gate in the rules file matches, and its error names the load failure. It also blocks every edit
26
+ inside the project when it cannot read the rules file or the file does not parse. Any other call
27
+ runs, and the hook reports the load failure as a non-blocking error.
24
28
 
25
- await runSkillGate();
26
- ```
27
-
28
- The `hook-skill-gate` entry of repo-sync delivers this file from zgeoff/tools. `runSkillGate` reads
29
- the hook payload from stdin, prints the hook output, and exits the process. Register the entry point
30
- in `.claude/settings.json`:
29
+ Register the entry point in `.claude/settings.json`, before a Bash command and after it:
31
30
 
32
31
  ```json
33
32
  {
@@ -42,6 +41,28 @@ in `.claude/settings.json`:
42
41
  }
43
42
  ]
44
43
  }
44
+ ],
45
+ "PostToolUse": [
46
+ {
47
+ "matcher": "Bash",
48
+ "hooks": [
49
+ {
50
+ "type": "command",
51
+ "command": "bun \"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-gate/skill-gate.ts\""
52
+ }
53
+ ]
54
+ }
55
+ ],
56
+ "PostToolUseFailure": [
57
+ {
58
+ "matcher": "Bash",
59
+ "hooks": [
60
+ {
61
+ "type": "command",
62
+ "command": "bun \"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-gate/skill-gate.ts\""
63
+ }
64
+ ]
65
+ }
45
66
  ]
46
67
  }
47
68
  }
@@ -50,9 +71,10 @@ in `.claude/settings.json`:
50
71
  ## Rules
51
72
 
52
73
  `.claude/skill-gate.json` maps path globs to the skills each path needs. `match` is a glob over the
53
- path from the repo root, and a path that holds an `ignore` segment is never gated. `Bun.Glob` misses
54
- deep paths for a `**` inside a brace group, such as `{e2e/**,test/**}`, so write one gate per
55
- pattern.
74
+ path from the repo root, and it matches files in dot folders such as `.claude/`. A path that holds
75
+ an `ignore` segment is never gated. The entry point matches with `Bun.Glob` when the package cannot
76
+ load, and `Bun.Glob` misses deep paths for a `**` inside a brace group, such as `{e2e/**,test/**}`,
77
+ so write one gate per pattern.
56
78
 
57
79
  ```json
58
80
  {
@@ -79,8 +101,40 @@ denies a gated edit until the session loads the skills again, and its denial say
79
101
 
80
102
  ## Bash commands
81
103
 
82
- The gate blocks only Edit, Write and MultiEdit. For Bash it reads the common forms of a shell write
83
- and warns, because a hook cannot parse every shell form: a deny built on a partial parser would
84
- block ordinary commands or let other writes through. A command the parser misses runs with no
85
- warning. Change a gated path only with Edit, Write or MultiEdit; the denial and the warning both say
86
- so.
104
+ The gate checks what a Bash command changed, not what the command says. Before the command, it
105
+ records `HEAD` and the content of each gated file that `git status` lists as changed, staged or
106
+ untracked. After the command, it reads `git status` again, plus the files that differ between the
107
+ old and the new `HEAD`. A gated file that the command created, changed, deleted, renamed or
108
+ committed counts as a change. A file that keeps its content does not: one dirty before and left
109
+ alone, or one whose mode alone changed, compared with its content at the old `HEAD`. A command that
110
+ moves `HEAD` another way, such as a pull or a checkout, counts each gated file it brought in. When
111
+ the session that ran the command lacks a skill that a changed file needs, the hook blocks: the agent
112
+ gets a reason that names the skills to load and asks it to review what the command changed. The same
113
+ load check as an edit applies, with its compaction and subagent rules.
114
+
115
+ Claude Code runs a `PostToolUse` hook after the command, so a block cannot undo the change. It stops
116
+ the agent's next step and puts the reason beside the command's output, as the
117
+ [hooks reference](https://code.claude.com/docs/en/hooks#posttooluse-decision-control) describes. A
118
+ command that exits with an error fires `PostToolUseFailure`, which cannot block, so the hook adds
119
+ the same reason as context.
120
+
121
+ Before the command runs, the gate also reads the common forms of a shell write, such as a redirect,
122
+ `tee`, `sed -i`, `cp`, `mv` or an inline script. When one targets a gated path, it warns and names
123
+ the skills to load. The warning is an early notice only, and the check after the command is the one
124
+ that blocks.
125
+
126
+ The check has limits:
127
+
128
+ - It needs a git work tree. Outside one, the gate gives only the early warning. When git fails
129
+ inside one, such as on an index it cannot read, the hook warns the user and the agent that the
130
+ command went unchecked.
131
+ - A command that runs in the background returns before it writes, so the check sees no change.
132
+ - A file that a git filter rewrites on checkout, such as a Git LFS file, never matches its content
133
+ at `HEAD`, so a mode change to one counts as a change.
134
+ - Bash commands that run in parallel share one work tree, so each one's check also sees the other's
135
+ changes.
136
+ - A command whose `PreToolUse` call left no record, such as one that started before the hook was
137
+ installed, goes unchecked.
138
+
139
+ Change a gated path only with Edit, Write or MultiEdit; the denial, the warning and the block all
140
+ say so.
@@ -0,0 +1,9 @@
1
+ import { z } from 'zod';
2
+ export declare const bashSnapshotSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
3
+ kind: z.ZodLiteral<"recorded">;
4
+ head: z.ZodNullable<z.ZodString>;
5
+ hashes: z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>;
6
+ }, z.core.$strip>, z.ZodObject<{
7
+ kind: z.ZodLiteral<"failed">;
8
+ error: z.ZodString;
9
+ }, z.core.$strip>], "kind">;
@@ -0,0 +1,4 @@
1
+ import type { BashChangeHookOutput, PostToolEvent } from './types.ts';
2
+ export declare function buildBashChangeOutput(event: PostToolEvent, changedPaths: readonly string[], missing: readonly string[], context?: {
3
+ readonly compacted?: boolean;
4
+ }): BashChangeHookOutput | null;
@@ -0,0 +1,2 @@
1
+ import type { BashCheckFailureHookOutput, PostToolEvent } from './types.ts';
2
+ export declare function buildBashCheckFailureOutput(event: PostToolEvent, error: string): BashCheckFailureHookOutput;
@@ -0,0 +1,2 @@
1
+ import type { BashCandidates, FileHashes } from './types.ts';
2
+ export declare function collectBashCandidates(recorded: FileHashes, gatedPaths: readonly string[]): BashCandidates;
@@ -0,0 +1,2 @@
1
+ import type { FileHashes } from './types.ts';
2
+ export declare function collectChangedPaths(recorded: FileHashes, atHead: FileHashes, after: FileHashes): readonly string[];