atp-hermes-hook 0.2.0 → 0.2.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 +23 -7
- package/package.json +1 -1
- package/src/setup.mjs +6 -2
package/README.md
CHANGED
|
@@ -9,13 +9,14 @@ Requires Node.js 20 or newer. Want to see the decisions before changing Hermes s
|
|
|
9
9
|
Requires Hermes on your PATH and Node.js 20 or newer. From any directory, run:
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
|
-
npx --yes atp-hermes-hook@0.2.
|
|
12
|
+
npx --yes atp-hermes-hook@0.2.1 setup
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
This creates an `atp-pilot` Hermes profile if needed, installs a fixed copy under
|
|
16
16
|
`~/.hermes/agent-hooks/atp`, and creates a `safe-default` policy that allows reads
|
|
17
17
|
only within a disposable test folder. Terminal, write and patch calls are blocked.
|
|
18
|
-
|
|
18
|
+
Every tool call is intercepted; unmapped tools, including `execute_code`, are blocked.
|
|
19
|
+
It runs standalone read/terminal/write and unmapped-tool decision checks, backs up the profile's
|
|
19
20
|
`config.yaml`, and merges a fail-closed hook while preserving other hooks and
|
|
20
21
|
settings. It does not install packages into your current directory.
|
|
21
22
|
|
|
@@ -39,7 +40,7 @@ Standalone checks do not prove live enforcement or signed mandate verification.
|
|
|
39
40
|
To choose another profile and read scope:
|
|
40
41
|
|
|
41
42
|
```bash
|
|
42
|
-
npx --yes atp-hermes-hook@0.2.
|
|
43
|
+
npx --yes atp-hermes-hook@0.2.1 setup --hermes-profile my-test-profile --read /absolute/path/to/docs
|
|
43
44
|
```
|
|
44
45
|
|
|
45
46
|
`--read` may be repeated; it replaces the default test-folder read scope on first
|
|
@@ -50,8 +51,20 @@ use manual installation for different policies per profile. `--hermes-home` sele
|
|
|
50
51
|
a custom Hermes root. Setup rejects malformed YAML, preserves existing ATP policies,
|
|
51
52
|
and refuses to replace their read scope implicitly. Rerunning setup does not add
|
|
52
53
|
duplicate copies of the same command. Existing manually configured ATP commands
|
|
53
|
-
are preserved with other hooks; review them separately if migrating.
|
|
54
|
-
|
|
54
|
+
are preserved with other hooks; review them separately if migrating. Unmapped
|
|
55
|
+
tools are blocked, so features such as code execution, browser automation and
|
|
56
|
+
delegation are unavailable until explicitly mapped and reviewed. Use WSL on Windows.
|
|
57
|
+
|
|
58
|
+
### Upgrade from 0.2.0 or a manual four-tool matcher
|
|
59
|
+
|
|
60
|
+
The earlier `^(read_file|terminal|write_file|patch)$` matcher did not intercept
|
|
61
|
+
`execute_code`. A live pilot reported a blocked terminal call followed by a
|
|
62
|
+
successful Python subprocess through that alternate tool. The four-tool check
|
|
63
|
+
therefore did not establish execution containment. Re-run setup at 0.2.1 to
|
|
64
|
+
replace the installer's matcher with `.*`, or update your manual matcher below.
|
|
65
|
+
Upgrading the package alone does not update profile YAML. Restart the affected
|
|
66
|
+
CLI session (and deliberately restart any affected gateway) after configuration
|
|
67
|
+
changes. Verify both `terminal` and `execute_code` are blocked through Hermes.
|
|
55
68
|
|
|
56
69
|
To undo the YAML change, restore the exact backup path printed by setup. This
|
|
57
70
|
restores the whole pre-setup file, so preserve later configuration edits first.
|
|
@@ -106,7 +119,7 @@ Then add the hook to your Hermes profile's `config.yaml`, using absolute paths:
|
|
|
106
119
|
```yaml
|
|
107
120
|
hooks:
|
|
108
121
|
pre_tool_call:
|
|
109
|
-
- matcher: "
|
|
122
|
+
- matcher: ".*"
|
|
110
123
|
command: "/home/me/.hermes/agent-hooks/atp/node_modules/.bin/atp-hermes-hook --config /home/me/.hermes/agent-hooks/atp/atp-hermes.json"
|
|
111
124
|
timeout: 10
|
|
112
125
|
fail_closed: true
|
|
@@ -139,7 +152,10 @@ Every block writes `{"action":"block","message":"ATP: ..."}` and **exits with co
|
|
|
139
152
|
| `patch` | `filesystem` (write) | `path` |
|
|
140
153
|
| `terminal` | `shell` | — |
|
|
141
154
|
|
|
142
|
-
|
|
155
|
+
Every tool reaches this hook. To permit another tool, map it explicitly after
|
|
156
|
+
reviewing its capabilities. Do not map a general interpreter to a harmless
|
|
157
|
+
category: `execute_code` can run subprocesses and access files directly.
|
|
158
|
+
For example, to evaluate a network tool and remove the terminal mapping:
|
|
143
159
|
|
|
144
160
|
```json
|
|
145
161
|
{
|
package/package.json
CHANGED
package/src/setup.mjs
CHANGED
|
@@ -7,7 +7,9 @@ import { randomUUID } from 'node:crypto';
|
|
|
7
7
|
import { parseDocument } from 'yaml';
|
|
8
8
|
import { loadConfig } from './index.mjs';
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
// Dispatch every tool through ATP. Otherwise an unmapped execution tool (for
|
|
11
|
+
// example execute_code -> subprocess) can route around a blocked terminal call.
|
|
12
|
+
const MATCHER = '.*';
|
|
11
13
|
const packageRoot = fileURLToPath(new URL('../', import.meta.url));
|
|
12
14
|
|
|
13
15
|
function run(command, args, options = {}) {
|
|
@@ -96,6 +98,8 @@ export function setupHermes({ profile = 'atp-pilot', hermesHome = process.env.HE
|
|
|
96
98
|
const tests = [
|
|
97
99
|
['terminal blocked', { tool_name: 'terminal', tool_input: { command: 'echo ATP-test' } }, 2],
|
|
98
100
|
['write blocked', { tool_name: 'write_file', tool_input: { path: fixture, content: 'must not be written' } }, 2],
|
|
101
|
+
['execute_code blocked', { tool_name: 'execute_code', tool_input: { code: 'import subprocess' } }, 2],
|
|
102
|
+
['unmapped tool blocked', { tool_name: 'future_execution_tool', tool_input: {} }, 2],
|
|
99
103
|
];
|
|
100
104
|
// The default fixture is the only read scope we can prove without reading a user's files.
|
|
101
105
|
if (config.roots.read.includes(fixtureDir)) {
|
|
@@ -131,7 +135,7 @@ export function setupHermes({ profile = 'atp-pilot', hermesHome = process.env.HE
|
|
|
131
135
|
output(`Configured Hermes profile: ${profile}`);
|
|
132
136
|
if (backup) output(`Backup: ${backup}`);
|
|
133
137
|
output(`Policy: ${policyFile}`);
|
|
134
|
-
output('Scope:
|
|
138
|
+
output('Scope: every pre_tool_call is checked. Unmapped tools, including execute_code, are blocked.');
|
|
135
139
|
output('Standalone self-tests passed. Live Hermes enforcement is not verified yet.');
|
|
136
140
|
output(`Next: hermes -p ${profile} hooks test pre_tool_call --for-tool terminal`);
|
|
137
141
|
output('Review and approve the local hook when Hermes requests first-use consent.');
|