@zgeoff/skill-gate 0.2.6 → 0.2.8
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 +27 -107
- package/dist/build-bash-change-output.d.ts +2 -0
- package/dist/build-bash-skill-gate-output.d.ts +2 -0
- package/dist/build-edit-output.d.ts +3 -0
- package/dist/build-patch-gate-output.d.ts +2 -0
- package/dist/classify-command-reads.d.ts +5 -0
- package/dist/collect-command-reads.d.ts +1 -0
- package/dist/collect-prompt-skills.d.ts +1 -0
- package/dist/collect-rule-warnings.d.ts +2 -0
- package/dist/harness.d.ts +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +744 -241
- package/dist/load-ledger.d.ts +6 -0
- package/dist/parse-hook-input.d.ts +3 -0
- package/dist/parse-patch-paths.d.ts +1 -0
- package/dist/parse-shell-commands.d.ts +3 -1
- package/dist/pick-harness-wording.d.ts +3 -0
- package/dist/read-available-skills.d.ts +1 -0
- package/dist/read-project-dir.d.ts +1 -0
- package/dist/read-session-loads.d.ts +2 -0
- package/dist/read-session-transcript.d.ts +2 -0
- package/dist/record-codex-loads.d.ts +3 -0
- package/dist/resolve-state-dir.d.ts +3 -0
- package/dist/run-skill-gate.d.ts +2 -1
- package/dist/types.d.ts +41 -0
- package/dist/with-ledger-lock.d.ts +1 -0
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# @zgeoff/skill-gate
|
|
2
2
|
|
|
3
|
-
The skill gate is a Claude Code hook that denies an edit until the session has loaded
|
|
4
|
-
the path needs, and names the missing skills. It denies a call to a gated tool, such as
|
|
5
|
-
the same way until the session has loaded the skills and read the reference files the
|
|
6
|
-
After a Bash command, it compares `git status` with the status before the command, and
|
|
7
|
-
when the command changed a gated file that the session lacks the skills for. The package
|
|
8
|
-
rules: each repo keeps its own in `.claude/skill-gate.json`, and a repo without that file
|
|
9
|
-
gate.
|
|
3
|
+
The skill gate is a Claude Code and Codex CLI hook that denies an edit until the session has loaded
|
|
4
|
+
every skill the path needs, and names the missing skills. It denies a call to a gated tool, such as
|
|
5
|
+
an MCP tool, the same way until the session has loaded the skills and read the reference files the
|
|
6
|
+
tool needs. After a Bash command, it compares `git status` with the status before the command, and
|
|
7
|
+
it blocks when the command changed a gated file that the session lacks the skills for. The package
|
|
8
|
+
holds no rules: each repo keeps its own in `.claude/skill-gate.json`, and a repo without that file
|
|
9
|
+
has no gate.
|
|
10
10
|
|
|
11
11
|
## Install
|
|
12
12
|
|
|
@@ -23,16 +23,9 @@ The hook runs a file in the repo that calls the package's `runSkillGate`, at
|
|
|
23
23
|
file from zgeoff/tools. `runSkillGate` reads the hook payload from stdin, prints the hook output,
|
|
24
24
|
and exits the process.
|
|
25
25
|
|
|
26
|
-
The entry point fails closed. When the package cannot load, the entry point blocks each edit that a
|
|
27
|
-
gate in the rules file matches, and its error names the load failure. It also blocks every edit
|
|
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.
|
|
32
|
-
|
|
33
26
|
Register the entry point in `.claude/settings.json`, before a Bash command and after it. The
|
|
34
|
-
`PreToolUse` matcher names each tool that a
|
|
35
|
-
|
|
27
|
+
`PreToolUse` matcher names each tool that a tool gate names, since the hook never sees a call that
|
|
28
|
+
the matcher skips. This example gates `mcp__tracker__update_ticket`:
|
|
36
29
|
|
|
37
30
|
```json
|
|
38
31
|
{
|
|
@@ -74,105 +67,32 @@ sees a call that the matcher skips. This example gates `mcp__tracker__update_tic
|
|
|
74
67
|
}
|
|
75
68
|
```
|
|
76
69
|
|
|
70
|
+
## Codex
|
|
71
|
+
|
|
72
|
+
The same entry point runs as a Codex hook when its command passes `--harness codex`, and it gates
|
|
73
|
+
`apply_patch` edits, gated tools and Bash commands as it does under Claude Code. Codex has no Skill
|
|
74
|
+
tool, so the gate keeps a ledger of what each session loaded.
|
|
75
|
+
[Gating Codex edits](../../docs/guides/skill-gate-codex.md) holds the `.codex/hooks.json` example,
|
|
76
|
+
the trust step and the ledger rules.
|
|
77
|
+
|
|
77
78
|
## Rules
|
|
78
79
|
|
|
79
|
-
`.claude/skill-gate.json` maps path globs to the skills each path needs
|
|
80
|
-
|
|
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.
|
|
80
|
+
`.claude/skill-gate.json` maps path globs to the skills each path needs, and the optional `tools`
|
|
81
|
+
list gates a tool call by name.
|
|
84
82
|
|
|
85
83
|
```json
|
|
86
84
|
{
|
|
87
85
|
"ignore": ["node_modules/", "dist/"],
|
|
88
|
-
"gates": [
|
|
89
|
-
|
|
90
|
-
{ "match": "**/*.md", "skills": ["docs-writing"] }
|
|
91
|
-
]
|
|
86
|
+
"gates": [{ "match": "**/*.md", "skills": ["docs-writing"] }],
|
|
87
|
+
"tools": [{ "tool": "mcp__tracker__update_ticket", "skills": ["ticket-review"] }]
|
|
92
88
|
}
|
|
93
89
|
```
|
|
94
90
|
|
|
95
|
-
|
|
96
|
-
|
|
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
|
|
91
|
+
[Writing skill-gate rules](../../docs/guides/skill-gate-rules.md) covers each key, the glob shapes
|
|
92
|
+
to avoid, and how the gate treats a mistake in the rules file.
|
|
105
93
|
|
|
106
|
-
|
|
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
|
-
```
|
|
94
|
+
## Documentation
|
|
123
95
|
|
|
124
|
-
The
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
## Which loads count
|
|
128
|
-
|
|
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 beside the main one:
|
|
133
|
-
`<session>/subagents/agent-<agent_id>.jsonl`, or
|
|
134
|
-
`<session>/subagents/workflows/<workflow_id>/agent-<agent_id>.jsonl` for a subagent that a workflow
|
|
135
|
-
started. A subagent therefore loads the skills itself, and the main session's loads never count for
|
|
136
|
-
it. A compaction writes a `compact_boundary` entry, and the loads and reads before it no longer
|
|
137
|
-
count: after a compaction, the gate denies a gated edit or tool call until the session loads the
|
|
138
|
-
skills and reads the references again, and its denial says so.
|
|
139
|
-
|
|
140
|
-
## Bash commands
|
|
141
|
-
|
|
142
|
-
The gate checks what a Bash command changed, not what the command says. Before the command, it
|
|
143
|
-
records `HEAD` and the content of each gated file that `git status` lists as changed, staged or
|
|
144
|
-
untracked. After the command, it reads `git status` again, plus the files that differ between the
|
|
145
|
-
old and the new `HEAD`. A gated file that the command created, changed, deleted, renamed or
|
|
146
|
-
committed counts as a change. A file that keeps its content does not: one dirty before and left
|
|
147
|
-
alone, or one whose mode alone changed, compared with its content at the old `HEAD`. A command that
|
|
148
|
-
moves `HEAD` another way, such as a pull or a checkout, counts each gated file it brought in. When
|
|
149
|
-
the session that ran the command lacks a skill that a changed file needs, the hook blocks: the agent
|
|
150
|
-
gets a reason that names the skills to load and asks it to review what the command changed. The same
|
|
151
|
-
load check as an edit applies, with its compaction and subagent rules.
|
|
152
|
-
|
|
153
|
-
Claude Code runs a `PostToolUse` hook after the command, so a block cannot undo the change. It stops
|
|
154
|
-
the agent's next step and puts the reason beside the command's output, as the
|
|
155
|
-
[hooks reference](https://code.claude.com/docs/en/hooks#posttooluse-decision-control) describes. A
|
|
156
|
-
command that exits with an error fires `PostToolUseFailure`, which cannot block, so the hook adds
|
|
157
|
-
the same reason as context.
|
|
158
|
-
|
|
159
|
-
Before the command runs, the gate also reads the common forms of a shell write, such as a redirect,
|
|
160
|
-
`tee`, `sed -i`, `cp`, `mv` or an inline script. When one targets a gated path, it warns and names
|
|
161
|
-
the skills to load. The warning is an early notice only, and the check after the command is the one
|
|
162
|
-
that blocks.
|
|
163
|
-
|
|
164
|
-
The check has limits:
|
|
165
|
-
|
|
166
|
-
- It needs a git work tree. Outside one, the gate gives only the early warning. When git fails
|
|
167
|
-
inside one, such as on an index it cannot read, the hook warns the user and the agent that the
|
|
168
|
-
command went unchecked.
|
|
169
|
-
- A command that runs in the background returns before it writes, so the check sees no change.
|
|
170
|
-
- A file that a git filter rewrites on checkout, such as a Git LFS file, never matches its content
|
|
171
|
-
at `HEAD`, so a mode change to one counts as a change.
|
|
172
|
-
- Bash commands that run in parallel share one work tree, so each one's check also sees the other's
|
|
173
|
-
changes.
|
|
174
|
-
- A command whose `PreToolUse` call left no record, such as one that started before the hook was
|
|
175
|
-
installed, goes unchecked.
|
|
176
|
-
|
|
177
|
-
Change a gated path only with Edit, Write or MultiEdit; the denial, the warning and the block all
|
|
178
|
-
say so.
|
|
96
|
+
[The skill gate architecture](../../docs/architecture/skill-gate.md) describes how the entry point
|
|
97
|
+
fails closed, which skill loads and reference reads the gate counts, and how it checks what a Bash
|
|
98
|
+
command changed.
|
|
@@ -1,4 +1,6 @@
|
|
|
1
|
+
import type { Harness } from './harness.ts';
|
|
1
2
|
import type { BashChangeHookOutput, PostToolEvent } from './types.ts';
|
|
2
3
|
export declare function buildBashChangeOutput(event: PostToolEvent, changedPaths: readonly string[], missing: readonly string[], context?: {
|
|
3
4
|
readonly compacted?: boolean;
|
|
5
|
+
readonly harness?: Harness;
|
|
4
6
|
}): BashChangeHookOutput | null;
|
|
@@ -1,4 +1,6 @@
|
|
|
1
|
+
import type { Harness } from './harness.ts';
|
|
1
2
|
import type { SkillGateHookOutput } from './types.ts';
|
|
2
3
|
export declare function buildBashSkillGateOutput(gatedPaths: readonly string[], missing: readonly string[], context?: {
|
|
3
4
|
readonly compacted?: boolean;
|
|
5
|
+
readonly harness?: Harness;
|
|
4
6
|
}): SkillGateHookOutput | null;
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
import type { Harness } from './harness.ts';
|
|
2
|
+
import type { EditEntry, SkillGateHookOutput, SkillGateOutputContext } from './types.ts';
|
|
3
|
+
export declare function buildEditOutput(harness: Harness, entries: readonly EditEntry[], context: SkillGateOutputContext): SkillGateHookOutput | null;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function collectCommandReads(command: string, cwd: string): readonly string[];
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function collectPromptSkills(prompt: string): readonly string[];
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export type Harness = 'claude-code' | 'codex';
|
package/dist/index.d.ts
CHANGED