Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

feat(gateguard): record opt-in decision metrics

Jeffrey Montoya4c035dd83490
diff --git a/docs/gateguard/design-notes.md b/docs/gateguard/design-notes.md
index 127e9bdf2..76e74eb2e 100644
--- a/docs/gateguard/design-notes.md
+++ b/docs/gateguard/design-notes.md
@@ -36,6 +36,9 @@ headings stable, since they are the anchors.
[Read-only first shell command](#read-only-first-shell-command)). Built by
`createReadOnlyShell()` from the hook's `quoteAwareSegments`, like the
search evidence.
+- `scripts/lib/gateguard-metrics.js`: builds, validates and appends the opt-in
+ decision metrics lines (see [Metrics](#metrics)). `scripts/gateguard-report.js`
+ reads them back.
## Fail to deny
@@ -500,3 +503,37 @@ key, so a subagent's retry never unlocks the path for the parent, whose own
first touch is still gated. The keys share the parent's state file when the
subagent's call carries the parent's session id. Exempt globs and Claude
settings files are skipped first, as at top level.
+
+## Metrics
+
+Decision metrics exist to show whether the gate asks the right question at the
+right time: how often it denies, how often prior-search credit, sibling
+collapse, trivial edits and the cap remove a denial, which questions it asks,
+and how often a denial followed a search that nearly counted.
+
+- **Opt-in.** Nothing is written unless `GATEGUARD_METRICS` is one of the
+ truthy spellings the other GateGuard switches accept. The variable is read
+ on every call, so it can be turned on for part of a session.
+- **Codes, never content.** A line holds the schema version, time, a 12-hex
+ sha256 prefix of the resolved session key (not the key itself), the tool,
+ the target class, the decision, a reason code, question ids, the sensitive
+ flag and the change-profile flags. Class, reason, question ids and language
+ must match a short lowercase code pattern or are written as `null`, so a
+ path, command, file content or transcript text cannot reach the file even
+ if a caller passed one by mistake. The session digest is one-way but not
+ secret: anyone holding the session id can link it to its lines.
+- **One write per call.** Decisions are collected while `run()` decides and
+ appended in one `appendFileSync` after it returns, including when it throws.
+ A MultiEdit call writes one line per distinct file it decided. Lazily
+ computed class and sensitivity for passes are only computed when metrics
+ are on.
+- **Never changes a decision.** Every metrics error (unwritable directory,
+ a directory in place of the file, a failed rotation) is ignored, and the
+ gate's result is returned unchanged.
+- **Bounded.** When an append would take `metrics.jsonl` past 1 MiB it is
+ renamed to `metrics.jsonl.1`, replacing the previous rotation, so the two
+ files together stay near 2 MiB. Concurrent hooks may interleave lines or
+ lose one rotation's worth of lines; the report skips anything malformed.
+- **Shell denials carry no question ids.** The destructive and routine shell
+ gates ask fixed questions that have no ids, so their lines have
+ `questions: null`, as do all passes.
diff --git a/docs/ja-JP/skills/gateguard/SKILL.md b/docs/ja-JP/skills/gateguard/SKILL.md
index ecccc9626..1ad788f7b 100644
--- a/docs/ja-JP/skills/gateguard/SKILL.md
+++ b/docs/ja-JP/skills/gateguard/SKILL.md
@@ -138,7 +138,8 @@ Triggers on: `rm -rf`, `git reset --hard`, `git push --force`, `drop table`, etc
- **セッション内カウンター:** 状態ファイルに `fact_force_credited`、`denials_by_class`、`credited_by_class`、`sibling_allows`、`dir_gates`、`cap_allows` を記録します(クラス名のみ記録し、パスは記録しません。`dir_gates` はサニタイズ済みの最初のファイル名のみ保持、最大 50 件)。
- **拒否の上限(オプトイン):** `GATEGUARD_FACT_FORCE_MAX_DENIALS` を設定すると、セッション内の初回タッチ拒否がその回数に達した後の新しいパスは拒否されずに通過します(`cap_allows` に記録)。`GATEGUARD_FACT_FORCE_FULL_DENIALS` はメッセージの詳しさ(メッセージ予算)だけを変えますが、こちらはブロックするかどうか(拒否予算)を変えます。事前検索のクレジットと兄弟ファイル集約が先に判定され、上限を消費しません。不正な値は上限なしとして扱い、stderr に 1 回警告します。
- **機密対象:** `.env`/`.env.*`、`*.pem`・`*.key`・`*.p12`・`*.pfx`、`id_rsa*`・`id_ed25519*`・`id_ecdsa*`・`id_dsa*`・`.netrc`・`.pgpass`・`credentials*`・`secrets.*`、パスセグメントが `auth`・`authn`・`authz`・`security`・`secrets`・`payment`・`payments`・`billing`・`migrations` のいずれかと完全一致するもの、`.github/workflows/` 配下は、クレジット・集約・上限のいずれも適用されず、初回タッチで必ず拒否されます。判定は字句上のパスとシンボリックリンクを解決した実体の両方で行い(`src/tools -> ../auth` なら `src/tools/login.py` も機密)、実体を解決できない場合は機密とみなします。判定順は exempt → subagent → checked → 機密? → クレジット → 兄弟集約 → 上限 → 拒否です。
-- **互換性:** 新しい環境変数はオプトインの `GATEGUARD_FACT_FORCE_MAX_DENIALS` のみです。以前許可されていた操作が拒否されることはありません。
+- **判定メトリクス(オプトイン):** `GATEGUARD_METRICS=1` で各判定を `<GATEGUARD_STATE_DIR>/metrics.jsonl` に 1 行ずつ記録します(パス・コマンド・内容は記録せず、1 MiB で `.1` にローテーション)。集計は `node scripts/gateguard-report.js [--dir <path>] [--json]` です。
+- **互換性:** 新しい環境変数はオプトインの `GATEGUARD_FACT_FORCE_MAX_DENIALS` と `GATEGUARD_METRICS` のみです。以前許可されていた操作が拒否されることはありません。
- **信頼の限界:** クレジットはローカルのトランスクリプトを読むため、エージェントが理論上それを書き換えられます。検証するのは行動(検索が実行され結果が返ったこと)であり、意図ではありません。
## Quick Start
diff --git a/docs/zh-CN/skills/gateguard/SKILL.md b/docs/zh-CN/skills/gateguard/SKILL.md
index 5bb280454..0d5e68d10 100644
--- a/docs/zh-CN/skills/gateguard/SKILL.md
+++ b/docs/zh-CN/skills/gateguard/SKILL.md
@@ -99,7 +99,8 @@ LLM 的自我评估不起作用。问"你是否违反了任何策略?"答案
* **拒绝上限(可选):** 设置 `GATEGUARD_FACT_FORCE_MAX_DENIALS` 后,会话内首次触碰的拒绝次数达到该值后,新路径直接放行(计入 `cap_allows`)。`GATEGUARD_FACT_FORCE_FULL_DENIALS` 只决定消息详略(消息预算),而此变量决定是否拦截(拒绝预算)。事先搜索抵免和同级合并先于上限判定,不消耗上限;格式错误的值视为无上限,并在 stderr 警告一次。
* **敏感目标:** `.env`/`.env.*`、`*.pem`/`*.key`/`*.p12`/`*.pfx`、`id_rsa*`/`id_ed25519*`/`id_ecdsa*`/`id_dsa*`/`.netrc`/`.pgpass`/`credentials*`/`secrets.*`、任一路径段恰为 `auth`、`authn`、`authz`、`security`、`secrets`、`payment`、`payments`、`billing`、`migrations`,以及 `.github/workflows/` 下的文件,不适用抵免、合并和上限,首次触碰总是拒绝。按字面路径和解析符号链接后的真实位置同时判定(`src/tools -> ../auth` 时 `src/tools/login.py` 也是敏感目标),真实位置无法解析时视为敏感。判定顺序:exempt → subagent → checked → 敏感? → 抵免 → 同级合并 → 上限 → 拒绝。
* **例行 shell 门控与会话:** 门控触发前,只读命令(`ls`、`cat`、`rg`、`git status`/`log`/`diff`、`Get-ChildItem` 等,不含重定向、替换、`tee`、`xargs` 或未知命令)直接放行且不消耗门控,计入 `routine_readonly_passes`;以会话 ID 或 transcript 路径为键的状态空闲 8 小时失效,项目目录回退键仍为 30 分钟;子代理对敏感目标每个路径拒绝一次(不会为父会话解锁)。
-* **兼容性:** 唯一新增的环境变量是可选的 `GATEGUARD_FACT_FORCE_MAX_DENIALS`;除子代理首次触碰敏感目标外,以前允许的操作不会变为拒绝,且从不返回 `permissionDecision: "allow"`。
+* **判定指标(可选):** 设置 `GATEGUARD_METRICS=1` 后,每次判定向 `<GATEGUARD_STATE_DIR>/metrics.jsonl` 追加一行(不记录路径、命令或内容,超过 1 MiB 轮转为 `.1`);用 `node scripts/gateguard-report.js [--dir <path>] [--json]` 汇总。
+* **兼容性:** 新增的环境变量只有可选的 `GATEGUARD_FACT_FORCE_MAX_DENIALS` 和 `GATEGUARD_METRICS`;除子代理首次触碰敏感目标外,以前允许的操作不会变为拒绝,且从不返回 `permissionDecision: "allow"`。
## 快速开始
diff --git a/manifests/context-packs/[email protected] b/manifests/context-packs/[email protected]
index 3693949af..fd48898b6 100644
--- a/manifests/context-packs/[email protected]
+++ b/manifests/context-packs/[email protected]
@@ -1 +1 @@
-{"coverage":{"skills":293,"withTriggers":32},"generatedAt":"2026-09-24T23:51:22.784Z","id":"skill-triggers@1","model":{"effort":null,"id":"hand-seeded","source":"manual-curation-pending-regeneration"},"registryDigest":"8327457d64c59c71b4c2d699226e9782854d2512ead87e2e6a2b4a65741d1c22","schemaVersion":1,"triggers":{"skill:api-connector-builder":["add api integration","new provider connector","match existing integration pattern"],"skill:api-design":["rest endpoint design","pagination api","status codes","api versioning","rate limiting api","resource naming","filtering api","api error responses","offset pagination","limit query parameter","pagination defaults"],"skill:backend-patterns":["express api","node backend architecture","nextjs api routes","server side patterns","data access layer","static file server","url path handling","file server"],"skill:browser-qa":["deployed feature test","visual regression screenshots","core web vitals check","axe accessibility audit","ship do not ship","staging verification"],"skill:canary-watch":["post deploy monitoring","smoke test url","production url check","console errors production","sse stream check","after deploy verification"],"skill:code-tour":["onboarding walkthrough","explain subsystem","architecture tour","pr walkthrough","rca tour"],"skill:coding-standards":["code review standards","naming conventions","readability review","immutability conventions","fix naming typo","export naming","consistent exports"],"skill:content-hash-cache-pattern":["cache file processing","content addressed cache","sha256 hash cache"],"skill:database-migrations":["zero downtime migration","schema change production","add column large table","backfill data","expand contract","concurrent index","migration rollback","prisma migration","django migration"],"skill:deployment-patterns":["ci cd setup","dockerize app","health checks","rollback strategy","production readiness","deploy pipeline","containerize application"],"skill:design-system":["design tokens","visual consistency audit","css custom properties","ui audit","design system bootstrap"],"skill:django-patterns":["django orm","drf api","django rest framework","django caching","django signals","django middleware"],"skill:django-security":["django authentication","csrf protection","sql injection prevention","xss prevention","django deployment security","role based access control","authorization middleware","permissions checks"],"skill:docker-patterns":["dockerfile review","docker compose setup","container security","multi service orchestration"],"skill:error-handling":["error types","retry logic","circuit breaker","user facing errors","exception handling patterns","typed errors","error boundaries","go error handling","custom error class","error codes","config validation"],"skill:evm-token-decimals":["token decimals","wei conversion","erc20 balance off","bridge token precision"],"skill:frontend-a11y":["aria attributes","screen reader support","focus management","semantic html","form labeling","keyboard navigation react","a11y lint errors"],"skill:git-workflow":["merge vs rebase","commit conventions","resolve merge conflict","branching strategy","clean up commits","pull request cleanup","git history tidy"],"skill:hexagonal-architecture":["ports and adapters","dependency injection boundaries","decouple domain from io"],"skill:kubernetes-patterns":["kubernetes manifests","kubectl debugging","pod probes","k8s rbac","autoscaling config","configmap secrets"],"skill:orch-fix-defect":["fix a bug","broken behavior","regression fix","reproduce bug","defect repair"],"skill:postgres-patterns":["slow postgres query","query optimization","index design","rls policies","supabase schema","postgres indexing","database performance","schema design postgres","postgres driver","node postgres","query planner"],"skill:python-patterns":["pythonic code","pep 8","type hints python","python code review","idiomatic python"],"skill:python-testing":["pytest fixtures","mocking python","parametrized tests","coverage python","tdd python"],"skill:redis-patterns":["cache aside pattern","distributed lock","redis rate limiting","cache invalidation"],"skill:regex-vs-llm-structured-text":["parse invoice","extract receipt data","text extraction pipeline","parse form fields","cheap document parser","extract table data","parse log lines","parse access logs","common log format","log line parsing"],"skill:rust-patterns":["rust ownership","borrow checker","rust error handling","traits rust","rust concurrency","idiomatic rust"],"skill:search-first":["find existing library","npm package research","before writing custom code","evaluate existing tools","add dependency research"],"skill:security-review":["security audit","authentication review","sanitize user input","secrets handling","payment security checklist","prevent injection attacks","secure api endpoints","authn authz review","vulnerability checklist","input validation security","parameterized queries","sql injection"],"skill:security-scan":["audit claude config","claudemd security","mcp server audit","agentshield scan","hook configuration audit","settings json security"],"skill:tdd-workflow":["write test first","failing test","red green refactor","test driven development","regression test first","write a regression test"],"skill:verification-loop":["pre pr checks","verification report","quality gates","build lint test coverage","before creating a pr"]},"triggersDigest":"25b97a9e06fc336c7cf95ab854ed1a41033a54bcd6e1fb1cf69dc906332462aa"}
+{"coverage":{"skills":293,"withTriggers":32},"generatedAt":"2026-09-24T23:51:22.784Z","id":"skill-triggers@1","model":{"effort":null,"id":"hand-seeded","source":"manual-curation-pending-regeneration"},"registryDigest":"e317b28aa98c37c96abc349b6a16a336db01bed47f9af25a240520c365a958d6","schemaVersion":1,"triggers":{"skill:api-connector-builder":["add api integration","new provider connector","match existing integration pattern"],"skill:api-design":["rest endpoint design","pagination api","status codes","api versioning","rate limiting api","resource naming","filtering api","api error responses","offset pagination","limit query parameter","pagination defaults"],"skill:backend-patterns":["express api","node backend architecture","nextjs api routes","server side patterns","data access layer","static file server","url path handling","file server"],"skill:browser-qa":["deployed feature test","visual regression screenshots","core web vitals check","axe accessibility audit","ship do not ship","staging verification"],"skill:canary-watch":["post deploy monitoring","smoke test url","production url check","console errors production","sse stream check","after deploy verification"],"skill:code-tour":["onboarding walkthrough","explain subsystem","architecture tour","pr walkthrough","rca tour"],"skill:coding-standards":["code review standards","naming conventions","readability review","immutability conventions","fix naming typo","export naming","consistent exports"],"skill:content-hash-cache-pattern":["cache file processing","content addressed cache","sha256 hash cache"],"skill:database-migrations":["zero downtime migration","schema change production","add column large table","backfill data","expand contract","concurrent index","migration rollback","prisma migration","django migration"],"skill:deployment-patterns":["ci cd setup","dockerize app","health checks","rollback strategy","production readiness","deploy pipeline","containerize application"],"skill:design-system":["design tokens","visual consistency audit","css custom properties","ui audit","design system bootstrap"],"skill:django-patterns":["django orm","drf api","django rest framework","django caching","django signals","django middleware"],"skill:django-security":["django authentication","csrf protection","sql injection prevention","xss prevention","django deployment security","role based access control","authorization middleware","permissions checks"],"skill:docker-patterns":["dockerfile review","docker compose setup","container security","multi service orchestration"],"skill:error-handling":["error types","retry logic","circuit breaker","user facing errors","exception handling patterns","typed errors","error boundaries","go error handling","custom error class","error codes","config validation"],"skill:evm-token-decimals":["token decimals","wei conversion","erc20 balance off","bridge token precision"],"skill:frontend-a11y":["aria attributes","screen reader support","focus management","semantic html","form labeling","keyboard navigation react","a11y lint errors"],"skill:git-workflow":["merge vs rebase","commit conventions","resolve merge conflict","branching strategy","clean up commits","pull request cleanup","git history tidy"],"skill:hexagonal-architecture":["ports and adapters","dependency injection boundaries","decouple domain from io"],"skill:kubernetes-patterns":["kubernetes manifests","kubectl debugging","pod probes","k8s rbac","autoscaling config","configmap secrets"],"skill:orch-fix-defect":["fix a bug","broken behavior","regression fix","reproduce bug","defect repair"],"skill:postgres-patterns":["slow postgres query","query optimization","index design","rls policies","supabase schema","postgres indexing","database performance","schema design postgres","postgres driver","node postgres","query planner"],"skill:python-patterns":["pythonic code","pep 8","type hints python","python code review","idiomatic python"],"skill:python-testing":["pytest fixtures","mocking python","parametrized tests","coverage python","tdd python"],"skill:redis-patterns":["cache aside pattern","distributed lock","redis rate limiting","cache invalidation"],"skill:regex-vs-llm-structured-text":["parse invoice","extract receipt data","text extraction pipeline","parse form fields","cheap document parser","extract table data","parse log lines","parse access logs","common log format","log line parsing"],"skill:rust-patterns":["rust ownership","borrow checker","rust error handling","traits rust","rust concurrency","idiomatic rust"],"skill:search-first":["find existing library","npm package research","before writing custom code","evaluate existing tools","add dependency research"],"skill:security-review":["security audit","authentication review","sanitize user input","secrets handling","payment security checklist","prevent injection attacks","secure api endpoints","authn authz review","vulnerability checklist","input validation security","parameterized queries","sql injection"],"skill:security-scan":["audit claude config","claudemd security","mcp server audit","agentshield scan","hook configuration audit","settings json security"],"skill:tdd-workflow":["write test first","failing test","red green refactor","test driven development","regression test first","write a regression test"],"skill:verification-loop":["pre pr checks","verification report","quality gates","build lint test coverage","before creating a pr"]},"triggersDigest":"25b97a9e06fc336c7cf95ab854ed1a41033a54bcd6e1fb1cf69dc906332462aa"}
diff --git a/scripts/hooks/gateguard-fact-force.js b/scripts/hooks/gateguard-fact-force.js
index d6484dd7d..4e73a39b2 100644
--- a/scripts/hooks/gateguard-fact-force.js
+++ b/scripts/hooks/gateguard-fact-force.js
@@ -44,6 +44,7 @@ const { scanCurrentTurn, createTurnScanner, currentTurnId, transcriptPathFor } =
const { createSearchEvidence } = require('../lib/gateguard-search-evidence');
const { profileChange } = require('../lib/gateguard-change-profile');
const { createReadOnlyShell } = require('../lib/gateguard-readonly-shell');
+const { appendMetrics, metricsEvent } = require('../lib/gateguard-metrics');
const {
getDenialCount,
getCreditedCount,
@@ -64,6 +65,7 @@ const {
// Session state — scoped per session to avoid cross-session races.
const STATE_DIR = process.env.GATEGUARD_STATE_DIR || path.join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.gateguard');
let activeStateFile = null;
+let activeSessionKey = '';
const SESSION_TIMEOUT_MS = 30 * 60 * 1000;
const SESSION_ID_TIMEOUT_MS = 8 * 60 * 60 * 1000;
@@ -1404,6 +1406,7 @@ function idleWindowForKey(sessionKey) {
function getStateFile(data) {
if (!activeStateFile) {
const sessionKey = resolveSessionKey(data);
+ activeSessionKey = sessionKey;
activeStateFile = path.join(STATE_DIR, `state-${sessionKey}.json`);
activeIdleWindowMs = idleWindowForKey(sessionKey);
}
@@ -1914,8 +1917,20 @@ function withNoteBeforeRetry(message, note) {
return `${message.slice(0, at)}${note}\n\n${message.slice(at)}`;
}
-function firstTouchDenial(filePath, { isWrite, denials, cls, sensitive, profile, miss }) {
+function denialReason(sensitive, missNote, miss) {
+ if (sensitive) return 'sensitive';
+ return missNote ? `near-miss:${miss.reason}` : 'first-touch';
+}
+
+function firstTouchDenial(filePath, { isWrite, denials, cls, sensitive, profile, miss, reason }) {
const missNote = sensitive ? '' : closestMissNote(miss);
+ recordDecision('deny', reason || denialReason(sensitive, missNote, miss), {
+ target: filePath,
+ cls,
+ sensitive,
+ profile,
+ questions: questionIdsFor(cls, isWrite, profile)
+ });
if (denials > getFullDenialBudget()) {
const action = isWrite ? 'creation' : 'edit';
return denyResult(condensedGateMsg(action, filePath, denials, cls, sensitive, profile, missNote), { includeRecoveryHint: false });
@@ -1996,6 +2011,7 @@ function denyResult(reason, options = {}) {
}
function allowWithStateWarning() {
+ recordDecision('pass', 'state-error');
return {
stderr: '[Fact-Forcing Gate] GateGuard state could not be persisted; allowing this operation to avoid a permanent retry loop. Check GATEGUARD_STATE_DIR or filesystem permissions.',
exitCode: 0
@@ -2092,7 +2108,7 @@ function subagentSensitiveDenial(filePath, data, isWrite) {
const cls = classifyTargetFor(filePath, data);
const { ok, denials } = markCheckedAndCountDenial(subKey, { cls });
if (!ok) return allowWithStateWarning();
- return firstTouchDenial(filePath, { isWrite, denials, cls, sensitive: true, profile: null, miss: null });
+ return firstTouchDenial(filePath, { isWrite, denials, cls, sensitive: true, profile: null, miss: null, reason: 'subagent-sensitive' });
}
// --- Change profile ---
@@ -2105,9 +2121,80 @@ function entriesFor(edits, fileKey, data) {
return edits.filter(edit => edit && typeof edit.file_path === 'string' && canonicalPathKey(edit.file_path, data) === fileKey);
}
+// --- Metrics ---
+// see docs/gateguard/design-notes.md#metrics
+
+let pendingMetrics = null;
+
+function isMetricsEnabled() {
+ return ECC_ENABLE_VALUES.has(normalizeEnvValue(process.env.GATEGUARD_METRICS));
+}
+
+function recordDecision(decision, reason, fields = {}) {
+ if (!pendingMetrics) return;
+ if (fields.key !== undefined) {
+ if (pendingMetrics.keys.has(fields.key)) return;
+ pendingMetrics.keys.add(fields.key);
+ }
+ pendingMetrics.entries.push({ ...fields, decision, reason });
+}
+
+function targetFacts(entry, data) {
+ if (!entry.target) {
+ return { cls: entry.cls === undefined ? null : entry.cls, sensitive: entry.sensitive === true };
+ }
+ try {
+ return {
+ cls: entry.cls === undefined ? classifyTargetFor(entry.target, data) : entry.cls,
+ sensitive: entry.sensitive === undefined ? isSensitiveTargetFor(entry.target, data) : entry.sensitive
+ };
+ } catch (_) {
+ return { cls: null, sensitive: false };
+ }
+}
+
+function flushMetrics() {
+ const batch = pendingMetrics;
+ pendingMetrics = null;
+ if (!batch || batch.entries.length === 0) return;
+ try {
+ const now = Date.now();
+ const events = batch.entries.map(entry =>
+ metricsEvent({
+ sessionKey: activeSessionKey,
+ tool: batch.tool,
+ ...targetFacts(entry, batch.data),
+ decision: entry.decision,
+ reason: entry.reason,
+ questions: entry.questions,
+ profile: entry.profile,
+ now
+ })
+ );
+ appendMetrics(STATE_DIR, events);
+ } catch (_) {
+ /* ignore */
+ }
+}
+
+function exemptReason(filePath, data) {
+ if (!filePath) return 'no-path';
+ if (isClaudeSettingsPath(filePath)) return 'claude-settings';
+ return isExemptPath(filePath, data) ? 'exempt-glob' : '';
+}
+
// --- Core logic (exported for run-with-flags.js) ---
function run(rawInput) {
+ pendingMetrics = null;
+ try {
+ return gate(rawInput);
+ } finally {
+ flushMetrics();
+ }
+}
+
+function gate(rawInput) {
let data;
try {
data = typeof rawInput === 'string' ? JSON.parse(rawInput) : rawInput;
@@ -2127,17 +2214,24 @@ function run(rawInput) {
// Normalize: case-insensitive matching via lookup map
const TOOL_MAP = { edit: 'Edit', write: 'Write', multiedit: 'MultiEdit', bash: 'Bash', powershell: 'PowerShell' };
const toolName = TOOL_MAP[rawToolName.toLowerCase()] || rawToolName;
+ if (isMetricsEnabled()) {
+ pendingMetrics = { tool: toolName, data, entries: [], keys: new Set() };
+ }
const inSubagent = isSubagentInvocation(data);
const getTurnScan = createTurnScanner(data);
if (toolName === 'Edit' || toolName === 'Write') {
const filePath = toolInput.file_path || '';
- if (!filePath || isClaudeSettingsPath(filePath) || isExemptPath(filePath, data)) {
+ const exempt = exemptReason(filePath, data);
+ if (exempt) {
+ recordDecision('pass-exempt', exempt, { target: filePath });
return rawInput; // allow
}
if (inSubagent) {
- return subagentSensitiveDenial(filePath, data, toolName === 'Write') || rawInput;
+ const denial = subagentSensitiveDenial(filePath, data, toolName === 'Write');
+ if (!denial) recordDecision('pass-subagent', 'subagent', { target: filePath });
+ return denial || rawInput;
}
const fileKey = canonicalPathKey(filePath, data);
@@ -2151,6 +2245,7 @@ function run(rawInput) {
if (!markCheckedAndCountCredit(fileKey, cls)) {
return allowWithStateWarning();
}
+ recordDecision('credit', 'prior-search', { target: filePath, cls, sensitive });
return { additionalContext: creditNote(credit, filePath), exitCode: 0 };
}
const profile = sensitive ? null : changeProfileFor(toolName, filePath, [toolInput], toolInput.content);
@@ -2158,6 +2253,7 @@ function run(rawInput) {
if (!countTrivialAllow()) {
return allowWithStateWarning();
}
+ recordDecision('trivial', 'comment-whitespace', { target: filePath, cls, sensitive, profile });
return { additionalContext: trivialNote(filePath), exitCode: 0 };
}
const turnId = isNewFile && !sensitive ? currentTurnId(getTurnScan()) : null;
@@ -2168,6 +2264,7 @@ function run(rawInput) {
if (!markCheckedAndCountSibling(fileKey)) {
return allowWithStateWarning();
}
+ recordDecision('sibling', 'same-turn-dir', { target: filePath, cls, sensitive, profile });
return { additionalContext: siblingNote(sibling), exitCode: 0 };
}
const dirGate = gateKey ? { key: gateKey, turn: turnId, first: sanitizePath(filePath) } : undefined;
@@ -2178,12 +2275,14 @@ function run(rawInput) {
}
if (denials === null) {
// see docs/gateguard/design-notes.md#denial-cap
+ recordDecision('cap', 'max-denials', { target: filePath, cls, sensitive, profile });
return rawInput;
}
const miss = sensitive ? null : findClosestMiss(getTurnScan(), filePath, isNewFile, data);
return firstTouchDenial(filePath, { isWrite: toolName === 'Write', denials, cls, sensitive, profile, miss });
}
+ recordDecision('pass-checked', 'checked', { target: filePath });
return rawInput; // allow
}
@@ -2196,6 +2295,7 @@ function run(rawInput) {
const denial = subagentSensitiveDenial(filePath, data, false);
if (denial) return denial;
}
+ recordDecision('pass-subagent', 'subagent');
return rawInput;
}
@@ -2203,7 +2303,11 @@ function run(rawInput) {
const trivialKeys = new Set();
for (const edit of edits) {
const filePath = edit.file_path || '';
- if (!filePath || isClaudeSettingsPath(filePath) || isExemptPath(filePath, data)) continue;
+ const exempt = exemptReason(filePath, data);
+ if (exempt) {
+ recordDecision('pass-exempt', exempt, { target: filePath, key: `exempt:${filePath}` });
+ continue;
+ }
const fileKey = canonicalPathKey(filePath, data);
if (trivialKeys.has(fileKey)) continue;
if (!isChecked([fileKey, filePath])) {
@@ -2214,6 +2318,7 @@ function run(rawInput) {
if (!markCheckedAndCountCredit(fileKey, cls)) {
return allowWithStateWarning();
}
+ recordDecision('credit', 'prior-search', { target: filePath, cls, sensitive, key: fileKey });
notes.push(creditNote(credit, filePath));
continue;
}
@@ -2223,6 +2328,7 @@ function run(rawInput) {
return allowWithStateWarning();
}
trivialKeys.add(fileKey);
+ recordDecision('trivial', 'comment-whitespace', { target: filePath, cls, sensitive, profile, key: fileKey });
notes.push(trivialNote(filePath));
continue;
}
@@ -2233,11 +2339,13 @@ function run(rawInput) {
}
if (denials === null) {
// see docs/gateguard/design-notes.md#denial-cap
+ recordDecision('cap', 'max-denials', { target: filePath, cls, sensitive, profile, key: fileKey });
continue;
}
const miss = sensitive ? null : findClosestMiss(getTurnScan(), filePath, false, data);
return firstTouchDenial(filePath, { isWrite: false, denials, cls, sensitive, profile, miss });
}
+ recordDecision('pass-checked', 'checked', { target: filePath, key: fileKey });
}
if (notes.length > 0) {
return { additionalContext: notes, exitCode: 0 };
@@ -2248,6 +2356,7 @@ function run(rawInput) {
if (toolName === 'Bash' || toolName === 'PowerShell') {
const command = toolInput.command || '';
if (isReadOnlyGitIntrospection(command)) {
+ recordDecision('pass', 'readonly-git');
return rawInput;
}
@@ -2258,8 +2367,10 @@ function run(rawInput) {
if (!markChecked(key)) {
return allowWithStateWarning();
}
+ recordDecision('destructive-deny', 'destructive');
return denyResult(destructiveBashMsg(), { includeRecoveryHint: false });
}
+ recordDecision('pass-checked', 'destructive-retry');
return rawInput; // allow retry after facts presented
}
@@ -2268,16 +2379,22 @@ function run(rawInput) {
// (Cursor, OpenCode, etc.) where the once-per-session routine gate is
// friction without signal.
if (isRoutineBashGateDisabled()) {
+ recordDecision('pass-exempt', 'routine-disabled');
return rawInput; // routine gate opted out via env
}
if (!isChecked(ROUTINE_BASH_SESSION_KEY)) {
if (isReadOnlyShellCommand(toolName, command)) {
- return countRoutineReadonlyPass() ? rawInput : allowWithStateWarning();
+ if (!countRoutineReadonlyPass()) {
+ return allowWithStateWarning();
+ }
+ recordDecision('routine-readonly', 'readonly');
+ return rawInput;
}
if (!markChecked(ROUTINE_BASH_SESSION_KEY)) {
return allowWithStateWarning();
}
+ recordDecision('routine-deny', 'first-command');
const hookId = toolName === 'PowerShell' ? POWERSHELL_HOOK_ID : BASH_HOOK_ID;
const narrowRecoveryHint = toolName === 'PowerShell'
? ROUTINE_POWERSHELL_NARROW_RECOVERY_HINT
@@ -2288,6 +2405,7 @@ function run(rawInput) {
});
}
+ recordDecision('pass-checked', 'routine-checked');
return rawInput; // allow
}
diff --git a/skills/gateguard/SKILL.md b/skills/gateguard/SKILL.md
index c23d5c50d..079675830 100644
--- a/skills/gateguard/SKILL.md
+++ b/skills/gateguard/SKILL.md
@@ -482,9 +482,10 @@ working.
### Compatibility and limits
-- **One new, opt-in environment variable:**
- `GATEGUARD_FACT_FORCE_MAX_DENIALS` (unset means no cap). The existing
- controls are unchanged.
+- **Two new, opt-in environment variables:**
+ `GATEGUARD_FACT_FORCE_MAX_DENIALS` (unset means no cap) and
+ `GATEGUARD_METRICS` (unset means no metrics). The existing controls are
+ unchanged.
- **Nothing previously allowed is now denied**, except a subagent's first
touch of a sensitive target. The other rules only remove denials, and never return `permissionDecision: "allow"`, so other hooks
and permission rules still apply.
@@ -526,10 +527,51 @@ load-bearing destructive-Bash checks keep running:
| `GATEGUARD_FACT_FORCE_MAX_DENIALS` | unset (no cap) | A **denial budget**: caps how many first-touch Edit/Write/MultiEdit denials a session draws. Once that many denials have been issued, further new paths pass through instead of being denied (counted in `cap_allows`, not as denials); `0` passes from the first. Prior-search credit and sibling collapse run first and never use it up, and [sensitive targets](#sensitive-targets) are always denied. Destructive and routine Bash stay gated. The cap is best effort when hooks run concurrently: a lost count update can add a denial, but never lets a new path through early. Opt-in: unset, or any value that is not a whole non-negative integer (surrounding spaces allowed), keeps the deny-every-new-path behaviour; a malformed value is reported once on stderr (`ignoring malformed GATEGUARD_FACT_FORCE_MAX_DENIALS=…; the denial cap is not active.`). Unlike `GATEGUARD_FACT_FORCE_FULL_DENIALS`, a **message budget** that only changes how much text a denial carries, this changes whether the operation is blocked. Condensed denials name this variable. |
| `GATEGUARD_BASH_EXTRA_DESTRUCTIVE` | unset | Extra destructive-command patterns, as regex source, added to the built-in set. A malformed regex is treated as unset (built-ins still apply) and logged once to stderr. |
| `GATEGUARD_STATE_DIR` | `~/.gateguard` | Where per-session gate state is kept. If state cannot be persisted the gate allows the operation rather than looping, and names this variable in the warning. |
+| `GATEGUARD_METRICS` | unset (off) | Records one line per Edit/Write/MultiEdit/Bash/PowerShell decision in `<GATEGUARD_STATE_DIR>/metrics.jsonl` (see [Decision metrics](#decision-metrics)). Never changes a decision. |
-`GATEGUARD_BASH_ROUTINE_DISABLED` accepts `1`, `true`, `on`, `enabled`,
-`enable`, or `yes` (case- and whitespace-insensitive); any other value
-leaves the gate on.
+`GATEGUARD_BASH_ROUTINE_DISABLED` and `GATEGUARD_METRICS` accept `1`, `true`,
+`on`, `enabled`, `enable`, or `yes` (case- and whitespace-insensitive); any
+other value leaves the routine gate on and metrics off.
+
+#### Decision metrics
+
+With `GATEGUARD_METRICS=1`, each gate decision appends one JSON line to
+`metrics.jsonl` in the state directory (a MultiEdit call writes one line per
+file it decided):
+
+```json
+{"v":1,"ts":"2026-09-01T10:02:00.000Z","session":"3f9c0a1b2d4e","tool":"Edit","class":"code","decision":"deny","reason":"near-miss:out-of-scope","questions":["local-callers","quote-instruction"],"sensitive":false,"profile":{"known":true,"language":"js","touchesPublicSurface":false,"touchesData":false,"trivial":false}}
+```
+
+| Field | Meaning |
+|---|---|
+| `v` | Schema version (`1`) |
+| `session` | First 12 hex characters of the sha256 of the session key |
+| `tool` | `Edit`, `Write`, `MultiEdit`, `Bash` or `PowerShell` |
+| `class` | Target class, or `null` for shell commands |
+| `decision` | `deny`, `credit`, `sibling`, `cap`, `trivial`, `pass-checked`, `pass-exempt`, `pass-subagent`, `routine-deny`, `routine-readonly`, `destructive-deny` or `pass` |
+| `reason` | Short code: `first-touch`, `sensitive`, `near-miss:<code>`, `subagent-sensitive`, `prior-search`, `comment-whitespace`, `same-turn-dir`, `max-denials`, `checked`, `exempt-glob`, `claude-settings`, `no-path`, `subagent`, `readonly-git`, `readonly`, `first-command`, `routine-checked`, `routine-disabled`, `destructive`, `destructive-retry`, `state-error` |
+| `questions` | Question ids of a first-touch denial; `null` otherwise |
+| `sensitive` | Whether the target is a [sensitive target](#sensitive-targets) |
+| `profile` | Change-profile flags when the profile was computed; `null` otherwise |
+
+**Privacy:** lines never contain paths, commands, file content, transcript
+text or the session id itself; every text field must be a short lowercase
+code or is written as `null`. Metrics errors are ignored. Past 1 MiB the file
+is renamed to `metrics.jsonl.1`, replacing the previous one.
+
+Summarise the metrics with:
+
+```bash
+node scripts/gateguard-report.js # GATEGUARD_STATE_DIR or ~/.gateguard
+node scripts/gateguard-report.js --dir /path/to/state --json
+```
+
+It reads `metrics.jsonl.1` then `metrics.jsonl`, skips malformed lines, and
+prints, per session and in total: decisions by type, denials by class and
+reason, the share of first-touch denials that followed a near-miss search,
+the rates of denial, credit, sibling collapse, cap and trivial edits among
+first touches, routine read-only passes, and the most-asked question ids.
#### Turning the gate off completely
diff --git a/tests/hooks/gateguard-metrics.test.js b/tests/hooks/gateguard-metrics.test.js
new file mode 100644
index 000000000..93801303a
--- /dev/null
+++ b/tests/hooks/gateguard-metrics.test.js
@@ -0,0 +1,395 @@
+/**
+ * Tests for opt-in GateGuard decision metrics written by scripts/hooks/gateguard-fact-force.js
+ */
+
+'use strict';
+
+const assert = require('assert');
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const runner = path.join(__dirname, '..', '..', 'scripts', 'hooks', 'run-with-flags.js');
+const SESSION_ID = 'gateguard-metrics-session';
+const SESSION_HASH = crypto.createHash('sha256').update(SESSION_ID).digest('hex').slice(0, 12);
+const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'gateguard-metrics-'));
+const projectRoot = path.join(tmpBase, 'fixture-project-zqx');
+const stateDir = path.join(tmpBase, 'state');
+const metricsFile = path.join(stateDir, 'metrics.jsonl');
+const transcriptDir = path.join(tmpBase, 'transcripts');
+fs.mkdirSync(path.join(projectRoot, 'src', 'widgets'), { recursive: true });
+fs.mkdirSync(transcriptDir, { recursive: true });
+
+const FIXTURE_STRINGS = [
+ 'fixture-project-zqx',
+ 'secret-widget-alpha',
+ 'quiet-helper-beta',
+ 'credited-gamma',
+ 'nearmiss-delta',
+ 'scaffold-epsilon',
+ 'scaffold-zeta',
+ 'capped-eta',
+ 'exempt-theta',
+ 'subagent-iota',
+ 'multi-kappa',
+ 'multi-lambda',
+ 'token-mu-echo',
+ 'token-nu-rm',
+ 'token-xi-ls',
+ 'token-omicron-ps',
+ 'CODE-BODY-PI',
+ 'COMMENT-BODY-RHO'
+];
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+ try {
+ fn();
+ console.log(` ✓ ${name}`);
+ passed++;
+ } catch (error) {
+ console.log(` ✗ ${name}`);
+ console.log(` Error: ${error.message}`);
+ failed++;
+ }
+}
+
+function resetState() {
+ fs.rmSync(stateDir, { recursive: true, force: true });
+ fs.mkdirSync(stateDir, { recursive: true });
+}
+
+function runHook(hookId, payload, env = {}) {
+ const result = spawnSync('node', [runner, hookId, 'scripts/hooks/gateguard-fact-force.js', 'standard,strict'], {
+ input: JSON.stringify({ cwd: projectRoot, ...payload }),
+ encoding: 'utf8',
+ env: {
+ ...process.env,
+ ECC_HOOK_PROFILE: 'standard',
+ GATEGUARD_STATE_DIR: stateDir,
+ CLAUDE_SESSION_ID: SESSION_ID,
+ CLAUDE_PROJECT_DIR: projectRoot,
+ CLAUDE_TRANSCRIPT_PATH: '',
+ GATEGUARD_METRICS: '1',
+ ...env
+ },
+ timeout: 15000
+ });
+ let decision = 'pass';
+ try {
+ const output = JSON.parse(result.stdout);
+ if (output && output.hookSpecificOutput && output.hookSpecificOutput.permissionDecision) {
+ decision = output.hookSpecificOutput.permissionDecision;
+ }
+ } catch (_) {
+ decision = 'pass';
+ }
+ return { status: result.status, decision, stdout: result.stdout || '' };
+}
+
+function edit(filePath, oldString = 'const a = 1;', newString = 'const a = 2;', extra = {}, env = {}) {
+ return runHook(
+ 'pre:edit-write:gateguard-fact-force',
+ { tool_name: 'Edit', tool_input: { file_path: filePath, old_string: oldString, new_string: newString }, ...extra },
+ env
+ );
+}
+
+function write(filePath, content, extra = {}, env = {}) {
+ return runHook('pre:edit-write:gateguard-fact-force', { tool_name: 'Write', tool_input: { file_path: filePath, content }, ...extra }, env);
+}
+
+function bash(command, env = {}) {
+ return runHook('pre:bash:gateguard-fact-force', { tool_name: 'Bash', tool_input: { command } }, env);
+}
+
+function powershell(command, env = {}) {
+ return runHook('pre:powershell:gateguard-fact-force', { tool_name: 'PowerShell', tool_input: { command } }, env);
+}
+
+function readEvents() {
+ if (!fs.existsSync(metricsFile)) return [];
+ return fs
+ .readFileSync(metricsFile, 'utf8')
+ .split('\n')
+ .filter(Boolean)
+ .map(line => JSON.parse(line));
+}
+
+function lastEvent() {
+ const events = readEvents();
+ return events[events.length - 1];
+}
+
+let transcriptSeq = 0;
+function writeTranscript(searches) {
+ transcriptSeq += 1;
+ const records = [{ type: 'user', uuid: `u-${transcriptSeq}-0`, message: { role: 'user', content: 'fix it' } }];
+ searches.forEach(([name, input], index) => {
+ const id = `toolu_${transcriptSeq}_${index}`;
+ records.push({
+ type: 'assistant',
+ uuid: `u-${transcriptSeq}-a${index}`,
+ message: { id: `msg_${id}`, role: 'assistant', content: [{ type: 'tool_use', id, name, input }] }
+ });
+ records.push({
+ type: 'user',
+ uuid: `u-${transcriptSeq}-r${index}`,
+ message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: id, is_error: false, content: 'ok' }] }
+ });
+ });
+ const pendingId = `toolu_pending_${transcriptSeq}`;
+ records.push({
+ type: 'assistant',
+ uuid: `u-${transcriptSeq}-p`,
+ message: { id: `msg_${pendingId}`, role: 'assistant', content: [{ type: 'tool_use', id: pendingId, name: 'Edit', input: {} }] }
+ });
+ const file = path.join(transcriptDir, `t-${transcriptSeq}.jsonl`);
+ fs.writeFileSync(file, records.map(r => JSON.stringify(r)).join('\n') + '\n', 'utf8');
+ return { transcript_path: file, tool_use_id: pendingId };
+}
+
+const src = name => path.join(projectRoot, 'src', name);
+
+console.log('\n=== Testing GateGuard decision metrics ===\n');
+
+test('writes no metrics file when GATEGUARD_METRICS is unset', () => {
+ resetState();
+ assert.strictEqual(edit(src('secret-widget-alpha.js'), 'a', 'b', {}, { GATEGUARD_METRICS: '' }).decision, 'deny');
+ assert.strictEqual(bash('echo token-mu-echo', { GATEGUARD_METRICS: '' }).decision, 'deny');
+ assert.strictEqual(fs.existsSync(metricsFile), false);
+});
+
+test('writes no metrics file for values outside the truthy set', () => {
+ resetState();
+ for (const value of ['0', 'false', 'off', 'nope']) {
+ edit(src(`secret-widget-alpha-${value}.js`), 'a', 'b', {}, { GATEGUARD_METRICS: value });
+ }
+ assert.strictEqual(fs.existsSync(metricsFile), false);
+});
+
+test('accepts the truthy spellings used by other GateGuard switches', () => {
+ for (const value of ['1', 'true', ' Yes ', 'on', 'enabled', 'enable']) {
+ resetState();
+ edit(src('secret-widget-alpha.js'), 'a', 'b', {}, { GATEGUARD_METRICS: value });
+ assert.strictEqual(readEvents().length, 1, `value ${JSON.stringify(value)}`);
+ }
+});
+
+test('records a first-touch denial with schema, session hash, class, questions and profile', () => {
+ resetState();
+ assert.strictEqual(edit(src('secret-widget-alpha.js'), 'const a = 1;', 'const a = 2;').decision, 'deny');
+ const events = readEvents();
+ assert.strictEqual(events.length, 1);
+ const event = events[0];
+ assert.deepStrictEqual(Object.keys(event).sort(), ['class', 'decision', 'profile', 'questions', 'reason', 'sensitive', 'session', 'tool', 'ts', 'v']);
+ assert.strictEqual(event.v, 1);
+ assert.ok(!Number.isNaN(Date.parse(event.ts)));
+ assert.strictEqual(event.session, SESSION_HASH);
+ assert.strictEqual(event.tool, 'Edit');
+ assert.strictEqual(event.class, 'code');
+ assert.strictEqual(event.decision, 'deny');
+ assert.strictEqual(event.reason, 'first-touch');
+ assert.strictEqual(event.sensitive, false);
+ assert.deepStrictEqual(event.questions, ['local-callers', 'quote-instruction']);
+ assert.deepStrictEqual(event.profile, { known: true, language: 'js', touchesPublicSurface: false, touchesData: false, trivial: false });
+});
+
+test('records a pass for an already checked file', () => {
+ edit(src('secret-widget-alpha.js'));
+ const event = lastEvent();
+ assert.strictEqual(event.decision, 'pass-checked');
+ assert.strictEqual(event.reason, 'checked');
+ assert.strictEqual(event.class, 'code');
+ assert.strictEqual(event.questions, null);
+ assert.strictEqual(event.profile, null);
+});
+
+test('records a sensitive denial with the full question set', () => {
+ resetState();
+ assert.strictEqual(edit(path.join(projectRoot, '.env.local'), 'A=1', 'A=2').decision, 'deny');
+ const event = lastEvent();
+ assert.strictEqual(event.decision, 'deny');
+ assert.strictEqual(event.reason, 'sensitive');
+ assert.strictEqual(event.sensitive, true);
+ assert.strictEqual(event.class, 'config');
+ assert.deepStrictEqual(event.questions, ['config-reader', 'config-effect', 'no-plaintext-secrets', 'quote-instruction']);
+});
+
+test('records a comment-only edit as trivial', () => {
+ resetState();
+ const result = edit(src('quiet-helper-beta.js'), 'run(); // COMMENT-BODY-RHO old', 'run(); // COMMENT-BODY-RHO new');
+ assert.strictEqual(result.decision, 'pass');
+ const event = lastEvent();
+ assert.strictEqual(event.decision, 'trivial');
+ assert.strictEqual(event.reason, 'comment-whitespace');
+ assert.strictEqual(event.profile.trivial, true);
+});
+
+test('records prior-search credit', () => {
+ resetState();
+ const turn = writeTranscript([['Grep', { pattern: 'credited-gamma', path: path.join(projectRoot, 'src') }]]);
+ assert.strictEqual(edit(src('credited-gamma.js'), 'a', 'b', turn).decision, 'pass');
+ const event = lastEvent();
+ assert.strictEqual(event.decision, 'credit');
+ assert.strictEqual(event.reason, 'prior-search');
+ assert.strictEqual(event.class, 'code');
+});
+
+test('records a near-miss denial with the miss code', () => {
+ resetState();
+ const turn = writeTranscript([['Grep', { pattern: 'nearmiss-delta', path: path.join(projectRoot, 'docs') }]]);
+ assert.strictEqual(edit(src('nearmiss-delta.js'), 'a', 'b', turn).decision, 'deny');
+ const event = lastEvent();
+ assert.strictEqual(event.decision, 'deny');
+ assert.strictEqual(event.reason, 'near-miss:out-of-scope');
+});
+
+test('records sibling collapse for a second new file in the same directory', () => {
+ resetState();
+ assert.strictEqual(write(path.join(projectRoot, 'src', 'widgets', 'scaffold-epsilon.js'), 'CODE-BODY-PI').decision, 'deny');
+ assert.strictEqual(write(path.join(projectRoot, 'src', 'widgets', 'scaffold-zeta.js'), 'CODE-BODY-PI').decision, 'pass');
+ const events = readEvents();
+ assert.deepStrictEqual(events.map(e => e.decision), ['deny', 'sibling']);
+ assert.deepStrictEqual(events[0].questions, ['callers', 'no-duplicate', 'quote-instruction']);
+ assert.strictEqual(events[1].reason, 'same-turn-dir');
+});
+
+test('records the denial cap', () => {
+ resetState();
+ assert.strictEqual(edit(src('capped-eta.js'), 'a', 'b', {}, { GATEGUARD_FACT_FORCE_MAX_DENIALS: '0' }).decision, 'pass');
+ const event = lastEvent();
+ assert.strictEqual(event.decision, 'cap');
+ assert.strictEqual(event.reason, 'max-denials');
+});
+
+test('records exempt and subagent passes', () => {
+ resetState();
+ edit(src('exempt-theta.js'), 'a', 'b', {}, { GATEGUARD_EXEMPT_GLOBS: 'src/exempt-*.js' });
+ edit(src('subagent-iota.js'), 'a', 'b', { agent_id: 'agent-1' });
+ const events = readEvents();
+ assert.deepStrictEqual(
+ events.map(e => [e.decision, e.reason]),
+ [
+ ['pass-exempt', 'exempt-glob'],
+ ['pass-subagent', 'subagent']
+ ]
+ );
+});
+
+test('records a subagent denial on a sensitive target', () => {
+ resetState();
+ assert.strictEqual(edit(path.join(projectRoot, 'src', 'auth', 'subagent-iota.js'), 'a', 'b', { agent_id: 'agent-1' }).decision, 'deny');
+ const event = lastEvent();
+ assert.strictEqual(event.decision, 'deny');
+ assert.strictEqual(event.reason, 'subagent-sensitive');
+ assert.strictEqual(event.sensitive, true);
+});
+
+test('records one line per file decided by a MultiEdit call', () => {
+ resetState();
+ const result = runHook('pre:edit-write:gateguard-fact-force', {
+ tool_name: 'MultiEdit',
+ tool_input: {
+ edits: [
+ { file_path: src('multi-kappa.js'), old_string: 'x(); // a', new_string: 'x(); // b' },
+ { file_path: src('multi-kappa.js'), old_string: 'y(); // a', new_string: 'y(); // b' },
+ { file_path: src('multi-lambda.js'), old_string: 'a', new_string: 'b' }
+ ]
+ }
+ });
+ assert.strictEqual(result.decision, 'deny');
+ const events = readEvents();
+ assert.deepStrictEqual(events.map(e => [e.tool, e.decision]), [
+ ['MultiEdit', 'trivial'],
+ ['MultiEdit', 'deny']
+ ]);
+});
+
+test('records shell decisions for Bash and PowerShell', () => {
+ resetState();
+ assert.strictEqual(bash('git status').decision, 'pass');
+ assert.strictEqual(bash('ls token-xi-ls').decision, 'pass');
+ assert.strictEqual(bash('rm -rf /tmp/token-nu-rm').decision, 'deny');
+ assert.strictEqual(bash('rm -rf /tmp/token-nu-rm').decision, 'pass');
+ assert.strictEqual(bash('echo token-mu-echo > out.txt').decision, 'deny');
+ assert.strictEqual(bash('echo token-mu-echo > out.txt').decision, 'pass');
+ assert.strictEqual(powershell('Get-ChildItem token-omicron-ps').decision, 'pass');
+ assert.strictEqual(bash('echo token-mu-echo', { GATEGUARD_BASH_ROUTINE_DISABLED: '1' }).decision, 'pass');
+ const events = readEvents();
+ assert.deepStrictEqual(
+ events.map(e => [e.tool, e.decision, e.reason]),
+ [
+ ['Bash', 'pass', 'readonly-git'],
+ ['Bash', 'routine-readonly', 'readonly'],
+ ['Bash', 'destructive-deny', 'destructive'],
+ ['Bash', 'pass-checked', 'destructive-retry'],
+ ['Bash', 'routine-deny', 'first-command'],
+ ['Bash', 'pass-checked', 'routine-checked'],
+ ['PowerShell', 'pass-checked', 'routine-checked'],
+ ['Bash', 'pass-exempt', 'routine-disabled']
+ ]
+ );
+ for (const event of events) {
+ assert.strictEqual(event.class, null);
+ assert.strictEqual(event.sensitive, false);
+ assert.strictEqual(event.questions, null);
+ assert.strictEqual(event.profile, null);
+ }
+});
+
+test('records a read-only first PowerShell command', () => {
+ resetState();
+ assert.strictEqual(powershell('Get-ChildItem token-omicron-ps').decision, 'pass');
+ assert.deepStrictEqual([lastEvent().tool, lastEvent().decision], ['PowerShell', 'routine-readonly']);
+});
+
+test('never writes paths, commands, content or session ids to the metrics file', () => {
+ resetState();
+ edit(src('secret-widget-alpha.js'), 'CODE-BODY-PI', 'CODE-BODY-PI 2');
+ edit(path.join(projectRoot, '.env.local'), 'A=1', 'A=2');
+ edit(src('quiet-helper-beta.js'), 'run(); // COMMENT-BODY-RHO old', 'run(); // COMMENT-BODY-RHO new');
+ const turn = writeTranscript([['Grep', { pattern: 'nearmiss-delta', path: path.join(projectRoot, 'docs') }]]);
+ edit(src('nearmiss-delta.js'), 'a', 'b', turn);
+ write(path.join(projectRoot, 'src', 'widgets', 'scaffold-epsilon.js'), 'CODE-BODY-PI');
+ write(path.join(projectRoot, 'src', 'widgets', 'scaffold-zeta.js'), 'CODE-BODY-PI');
+ bash('rm -rf /tmp/token-nu-rm');
+ bash('echo token-mu-echo > out.txt');
+ powershell('Get-ChildItem token-omicron-ps');
+ const combined = fs.readFileSync(metricsFile, 'utf8');
+ assert.ok(combined.split('\n').filter(Boolean).length >= 9);
+ for (const fixture of [...FIXTURE_STRINGS, SESSION_ID, tmpBase, '/tmp', '.env', 'rm -rf', 'Grep']) {
+ assert.ok(!combined.includes(fixture), `metrics must not contain ${fixture}`);
+ }
+});
+
+test('rotates the file past 1 MiB and replaces the previous rotation', () => {
+ resetState();
+ fs.writeFileSync(`${metricsFile}.1`, 'stale\n', 'utf8');
+ const filler = `${JSON.stringify({ v: 1, filler: 'x'.repeat(200) })}\n`;
+ fs.writeFileSync(metricsFile, filler.repeat(Math.ceil((1024 * 1024) / filler.length)), 'utf8');
+ const before = fs.statSync(metricsFile).size;
+ assert.ok(before >= 1024 * 1024);
+ edit(src('secret-widget-alpha.js'));
+ assert.strictEqual(fs.statSync(`${metricsFile}.1`).size, before);
+ assert.strictEqual(readEvents().length, 1);
+ assert.strictEqual(lastEvent().decision, 'deny');
+});
+
+test('keeps the gate decision when the metrics file cannot be written', () => {
+ resetState();
+ fs.mkdirSync(metricsFile);
+ const result = edit(src('secret-widget-alpha.js'));
+ assert.strictEqual(result.status, 0);
+ assert.strictEqual(result.decision, 'deny');
+ assert.strictEqual(bash('echo token-mu-echo').decision, 'deny');
+});
+
+fs.rmSync(tmpBase, { recursive: true, force: true });
+
+console.log(`\n ${passed} passed, ${failed} failed\n`);
+process.exit(failed > 0 ? 1 : 0);