@zgeoff/skill-gate 0.2.3 → 0.2.5

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,12 @@
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. It denies a call to a gated tool, such as an MCP tool,
5
+ the same way until the session has loaded the skills and read the reference files the tool needs.
6
+ After a Bash command, it compares `git status` with the status before the command, and it blocks
7
+ when the command changed a gated file that the session lacks the skills for. The package holds no
8
+ rules: each repo keeps its own in `.claude/skill-gate.json`, and a repo without that file has no
9
+ gate.
8
10
 
9
11
  ## Install
10
12
 
@@ -23,17 +25,43 @@ and exits the process.
23
25
 
24
26
  The entry point fails closed. When the package cannot load, the entry point blocks each edit that a
25
27
  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.
28
+ inside the project when it cannot read the rules file or the file does not parse. It blocks a call
29
+ to a tool that a tool gate names, and every call other than an edit or a Bash command when it cannot
30
+ read the rules file or the file or its `tools` list does not parse. Any other call runs, and the
31
+ hook reports the load failure as a non-blocking error.
28
32
 
29
- Register the entry point in `.claude/settings.json`:
33
+ Register the entry point in `.claude/settings.json`, before a Bash command and after it. The
34
+ `PreToolUse` matcher names each tool that a [tool gate](#tool-gates) names, since the hook never
35
+ sees a call that the matcher skips. This example gates `mcp__tracker__update_ticket`:
30
36
 
31
37
  ```json
32
38
  {
33
39
  "hooks": {
34
40
  "PreToolUse": [
35
41
  {
36
- "matcher": "Edit|Write|MultiEdit|Bash",
42
+ "matcher": "Edit|Write|MultiEdit|Bash|mcp__tracker__update_ticket",
43
+ "hooks": [
44
+ {
45
+ "type": "command",
46
+ "command": "bun \"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-gate/skill-gate.ts\""
47
+ }
48
+ ]
49
+ }
50
+ ],
51
+ "PostToolUse": [
52
+ {
53
+ "matcher": "Bash",
54
+ "hooks": [
55
+ {
56
+ "type": "command",
57
+ "command": "bun \"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-gate/skill-gate.ts\""
58
+ }
59
+ ]
60
+ }
61
+ ],
62
+ "PostToolUseFailure": [
63
+ {
64
+ "matcher": "Bash",
37
65
  "hooks": [
38
66
  {
39
67
  "type": "command",
@@ -49,9 +77,10 @@ Register the entry point in `.claude/settings.json`:
49
77
  ## Rules
50
78
 
51
79
  `.claude/skill-gate.json` maps path globs to the skills each path needs. `match` is a glob over the
52
- path from the repo root, and a path that holds an `ignore` segment is never gated. `Bun.Glob` misses
53
- deep paths for a `**` inside a brace group, such as `{e2e/**,test/**}`, so write one gate per
54
- pattern.
80
+ path from the repo root, and it matches files in dot folders such as `.claude/`. A path that holds
81
+ an `ignore` segment is never gated. The entry point matches with `Bun.Glob` when the package cannot
82
+ load, and `Bun.Glob` misses deep paths for a `**` inside a brace group, such as `{e2e/**,test/**}`,
83
+ so write one gate per pattern.
55
84
 
56
85
  ```json
57
86
  {
@@ -64,22 +93,85 @@ pattern.
64
93
  ```
65
94
 
66
95
  The gate skips a skill that a rule names but `.claude/skills/` lacks, and it still requires the
67
- rule's other skills. A rules file that does not parse denies no edit. In both cases the hook warns
68
- the user and the agent on every edit until the rules file is fixed.
96
+ rule's other skills. A rules file that does not parse denies no edit and no tool call. In both cases
97
+ the hook warns the user and the agent on every edit, and on every call to a tool that the hook
98
+ matcher names, until the rules file is fixed.
99
+
100
+ The gate skips a key it does not know, at the top level or inside a gate, and keeps the rest of the
101
+ rules. It warns on every edit and every gated tool call, and the key itself denies nothing. A rules
102
+ file written for a later version of the package therefore never blocks every call.
103
+
104
+ ### Tool gates
105
+
106
+ The optional `tools` list gates a tool call by its `PreToolUse` tool name. Each gate names the
107
+ `tool`, the `skills` the session loads, and the `references` it reads, and it needs at least one
108
+ skill or reference. A reference is a file path under `.claude/skills/`. A tool gate never names
109
+ `Edit`, `Write`, `MultiEdit` or `Bash`, since path gates cover those tools.
110
+
111
+ ```json
112
+ {
113
+ "gates": [],
114
+ "tools": [
115
+ {
116
+ "tool": "mcp__tracker__update_ticket",
117
+ "skills": ["ticket-review"],
118
+ "references": ["ticket-review/references/reasons.md"]
119
+ }
120
+ ]
121
+ }
122
+ ```
123
+
124
+ The denial names each missing skill and each reference to read. The gate skips a skill or a
125
+ reference that the repo lacks, and warns on each gated call until the rule is fixed.
69
126
 
70
127
  ## Which loads count
71
128
 
72
- The gate counts the loads of the session that makes the edit. A subagent's tool call carries
73
- `agent_id` beside the main session's `transcript_path`, and the gate reads that subagent's own
74
- transcript, `<session>/subagents/agent-<agent_id>.jsonl` beside the main one. A subagent therefore
75
- loads the skills itself, and the main session's loads never count for it. A compaction writes a
76
- `compact_boundary` entry, and the loads before it no longer count: after a compaction, the gate
77
- denies a gated edit until the session loads the skills again, and its denial says so.
129
+ The gate counts the loads of the session that makes the edit or the tool call. A skill loads through
130
+ a Skill tool call or a slash command. A reference counts once a Read tool call of its file succeeds;
131
+ a Bash `cat` of the file does not count. A subagent's tool call carries `agent_id` beside the main
132
+ session's `transcript_path`, and the gate reads that subagent's own transcript,
133
+ `<session>/subagents/agent-<agent_id>.jsonl` beside the main one. A subagent therefore loads the
134
+ skills itself, and the main session's loads never count for it. A compaction writes a
135
+ `compact_boundary` entry, and the loads and reads before it no longer count: after a compaction, the
136
+ gate denies a gated edit or tool call until the session loads the skills and reads the references
137
+ again, and its denial says so.
78
138
 
79
139
  ## Bash commands
80
140
 
81
- The gate blocks only Edit, Write and MultiEdit. For Bash it reads the common forms of a shell write
82
- and warns, because a hook cannot parse every shell form: a deny built on a partial parser would
83
- block ordinary commands or let other writes through. A command the parser misses runs with no
84
- warning. Change a gated path only with Edit, Write or MultiEdit; the denial and the warning both say
85
- so.
141
+ The gate checks what a Bash command changed, not what the command says. Before the command, it
142
+ records `HEAD` and the content of each gated file that `git status` lists as changed, staged or
143
+ untracked. After the command, it reads `git status` again, plus the files that differ between the
144
+ old and the new `HEAD`. A gated file that the command created, changed, deleted, renamed or
145
+ committed counts as a change. A file that keeps its content does not: one dirty before and left
146
+ alone, or one whose mode alone changed, compared with its content at the old `HEAD`. A command that
147
+ moves `HEAD` another way, such as a pull or a checkout, counts each gated file it brought in. When
148
+ the session that ran the command lacks a skill that a changed file needs, the hook blocks: the agent
149
+ gets a reason that names the skills to load and asks it to review what the command changed. The same
150
+ load check as an edit applies, with its compaction and subagent rules.
151
+
152
+ Claude Code runs a `PostToolUse` hook after the command, so a block cannot undo the change. It stops
153
+ the agent's next step and puts the reason beside the command's output, as the
154
+ [hooks reference](https://code.claude.com/docs/en/hooks#posttooluse-decision-control) describes. A
155
+ command that exits with an error fires `PostToolUseFailure`, which cannot block, so the hook adds
156
+ the same reason as context.
157
+
158
+ Before the command runs, the gate also reads the common forms of a shell write, such as a redirect,
159
+ `tee`, `sed -i`, `cp`, `mv` or an inline script. When one targets a gated path, it warns and names
160
+ the skills to load. The warning is an early notice only, and the check after the command is the one
161
+ that blocks.
162
+
163
+ The check has limits:
164
+
165
+ - It needs a git work tree. Outside one, the gate gives only the early warning. When git fails
166
+ inside one, such as on an index it cannot read, the hook warns the user and the agent that the
167
+ command went unchecked.
168
+ - A command that runs in the background returns before it writes, so the check sees no change.
169
+ - A file that a git filter rewrites on checkout, such as a Git LFS file, never matches its content
170
+ at `HEAD`, so a mode change to one counts as a change.
171
+ - Bash commands that run in parallel share one work tree, so each one's check also sees the other's
172
+ changes.
173
+ - A command whose `PreToolUse` call left no record, such as one that started before the hook was
174
+ installed, goes unchecked.
175
+
176
+ Change a gated path only with Edit, Write or MultiEdit; the denial, the warning and the block all
177
+ 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 { SkillGateHookOutput, SkillGateOutputContext, ToolGatePlan } from './types.ts';
2
+ export declare function buildToolGateOutput(toolName: string, plan: ToolGatePlan, context?: SkillGateOutputContext): SkillGateHookOutput | null;
@@ -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[];
@@ -0,0 +1,2 @@
1
+ import type { SessionLoads } from './types.ts';
2
+ export declare function collectSessionLoads(transcript: string): SessionLoads;
@@ -0,0 +1 @@
1
+ export declare function formatUnknownKeyWarning(key: string): string;