@akasecurity/ai-tc-antigravity 0.9.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/LICENSE +201 -0
- package/hooks.json +50 -0
- package/package.json +44 -0
- package/plugin.json +14 -0
- package/scripts/apply-suppressions.js +29689 -0
- package/scripts/backfill.js +30691 -0
- package/scripts/dashboard.js +46 -0
- package/scripts/filescan.js +31353 -0
- package/scripts/firstrun.js +28892 -0
- package/scripts/intro.js +18614 -0
- package/scripts/onboard.js +26577 -0
- package/scripts/post-tool-use.js +18743 -0
- package/scripts/pre-invocation.js +30069 -0
- package/scripts/pre-tool-use.js +30065 -0
- package/scripts/query.js +29168 -0
- package/scripts/reconcile.js +29320 -0
- package/scripts/remediate.js +30607 -0
- package/scripts/scan-worker.js +18006 -0
- package/scripts/start-light.js +18756 -0
- package/scripts/stop.js +18743 -0
- package/scripts/triage-rubric.md +93 -0
- package/skills/audit/SKILL.md +20 -0
- package/skills/dashboard/SKILL.md +27 -0
- package/skills/detections/SKILL.md +31 -0
- package/skills/exceptions/SKILL.md +27 -0
- package/skills/findings/SKILL.md +24 -0
- package/skills/health/SKILL.md +21 -0
- package/skills/recommend/SKILL.md +22 -0
- package/skills/scan/SKILL.md +70 -0
- package/skills/setup/SKILL.md +928 -0
- package/skills/tokens/SKILL.md +24 -0
|
@@ -0,0 +1,928 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: aka-setup
|
|
3
|
+
description: Set up AKA Security — calibrate notifications and detection posture from Antigravity's real activity.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# AKA setup wizard
|
|
7
|
+
|
|
8
|
+
You are onboarding the AKA Security plugin for this machine. AKA works
|
|
9
|
+
fully locally with **zero backend and zero Docker**: detection runs in-process
|
|
10
|
+
and findings persist to a local SQLite store at `~/.aka/data/aka.db`.
|
|
11
|
+
|
|
12
|
+
This wizard tells a **calibration story**: introduce AKA → show what it does →
|
|
13
|
+
offer one retroactive scan → report the real numbers it found and the posture it
|
|
14
|
+
recommends → apply on confirmation → show the installed summary → hand off to the
|
|
15
|
+
dashboard. Everything the user sees is derived from their _actual_ history — never
|
|
16
|
+
a fabricated or demo number. When there isn't enough history to judge, the wizard
|
|
17
|
+
falls back to a conservative severity-derived floor instead of guessing.
|
|
18
|
+
|
|
19
|
+
The false-positive/severity judgment needs the raw (unmasked) findings to rate
|
|
20
|
+
them accurately, so it **sends them to the model API** through separate `agy -p`
|
|
21
|
+
subprocesses (a large history is judged in several batches). Two things
|
|
22
|
+
cross for each finding: its **raw value**, and about **120 characters of the
|
|
23
|
+
surrounding transcript text** on either side of it — re-masked first, so any
|
|
24
|
+
_other_ detectable secret in that window never leaves raw. The transcript
|
|
25
|
+
file's path, the value's fingerprint, and the fingerprint key version are
|
|
26
|
+
**dropped before egress**. A copy of the raw value **leaves the machine**, sent
|
|
27
|
+
to the model provider like any other Antigravity prompt. You act only on the
|
|
28
|
+
raw-free plan the subprocesses print back.
|
|
29
|
+
|
|
30
|
+
Three limits of this host are worth knowing before you consent, because they
|
|
31
|
+
are weaker than the Claude Code and Codex plugins' equivalents:
|
|
32
|
+
|
|
33
|
+
- **The `agy` CLI documents no ephemeral mode.** Every run is written to your
|
|
34
|
+
conversation store under `~/.gemini/antigravity/brain/`, raw values and
|
|
35
|
+
all — the same store this backfill scans. AKA therefore **deletes the judge's
|
|
36
|
+
own conversation itself** as soon as the run ends. That deletion is best
|
|
37
|
+
effort: if the process is killed between the write and the cleanup, the
|
|
38
|
+
conversation stays on disk until you remove it.
|
|
39
|
+
- **The prompt travels on the command line**, because `agy` documents no way to
|
|
40
|
+
read a prompt from stdin. For the life of each run the raw values are visible
|
|
41
|
+
to anything that can list processes (`ps`) on this machine.
|
|
42
|
+
- **Deleting the conversation is not network isolation.** It is a local-write
|
|
43
|
+
cleanup only; it cannot recall what was already sent.
|
|
44
|
+
|
|
45
|
+
Reading history is granted in step 1; **sending findings to the model is a
|
|
46
|
+
distinct consent, collected in step 3 before the judgment pipe runs** — the
|
|
47
|
+
judge refuses to run without it.
|
|
48
|
+
|
|
49
|
+
Follow the steps below **in order**. Nothing is written to the policy store
|
|
50
|
+
until step 5 (or a floor fallback in step 3 if the calibration can't complete).
|
|
51
|
+
|
|
52
|
+
## Execution contract (read before step 0)
|
|
53
|
+
|
|
54
|
+
Every script prints output in three region kinds. Your job for each is fixed:
|
|
55
|
+
|
|
56
|
+
- **`<<<AKA_SHOW … AKA_SHOW>>>`** — relay every AKA_SHOW region verbatim as your
|
|
57
|
+
next message: paste the content _between_ the markers exactly — a card region
|
|
58
|
+
carries its own code fence, a plain confirmation line does not, but either way
|
|
59
|
+
you paste exactly what's between the markers — never the marker lines, never a
|
|
60
|
+
paraphrase or summary.
|
|
61
|
+
- **`<<<AKA_FRAME_JSON … AKA_FRAME_JSON>>>`** — machine-only. Parse it if a step
|
|
62
|
+
tells you to read a value from it; never display it.
|
|
63
|
+
- **Anything else on stdout** — status for you (paths like `Plan saved to:`,
|
|
64
|
+
errors, exit signals). Act on it; never relay it.
|
|
65
|
+
|
|
66
|
+
**Collecting a decision.** Wherever a step asks the user a question, ask it as a
|
|
67
|
+
normal conversational turn with numbered options for the user to pick from. This
|
|
68
|
+
wizard depends on no specific interactive-picker tool being available — present
|
|
69
|
+
each option clearly and wait for the user's reply before moving on. If Antigravity
|
|
70
|
+
exposes a native multi-choice picker in your environment, prefer that over plain
|
|
71
|
+
text; otherwise the numbered-list form is the fallback. Never answer a question
|
|
72
|
+
on the user's behalf.
|
|
73
|
+
|
|
74
|
+
Invariants:
|
|
75
|
+
|
|
76
|
+
- **Never write a confirmation or acknowledgement the wizard did not emit** — the
|
|
77
|
+
script's AKA_SHOW line is the confirmation.
|
|
78
|
+
- **Each step's AKA_SHOW regions must be relayed before you advance.**
|
|
79
|
+
- **One question per decision; never re-ask a decision already collected.**
|
|
80
|
+
|
|
81
|
+
## 0. Show the intro card
|
|
82
|
+
|
|
83
|
+
Run the intro script and relay its AKA_SHOW region per the execution contract:
|
|
84
|
+
paste the content between the markers verbatim, never the marker lines. It
|
|
85
|
+
prints a single space-aligned monospace card — name, repository, version, and
|
|
86
|
+
what AKA adds — inside a Markdown code fence that is part of that pasted
|
|
87
|
+
content. Keep the fence as printed and do **not** add another code fence, strip
|
|
88
|
+
the fence, or reformat it (unfenced, Markdown collapses the indentation and
|
|
89
|
+
mangles the `●` lines).
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
node "${PLUGIN_ROOT}/scripts/intro.js" "${PLUGIN_ROOT}/.antigravity-plugin/plugin.json"
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## 0b. Repo-aware posture check — tighten-only, working-tree only
|
|
96
|
+
|
|
97
|
+
Before showing any recommended posture — the start-light default table in
|
|
98
|
+
step 2 or the calibrated posture in step 4 — look at the **current project's**
|
|
99
|
+
working tree yourself, with your own file-reading tools. There is no script for
|
|
100
|
+
this: it is your own reasoning over facts you read directly, not the triage
|
|
101
|
+
subprocess's raw-free plan, and it needs no user interaction.
|
|
102
|
+
|
|
103
|
+
**In scope:** the manifest's declared frameworks/dependencies
|
|
104
|
+
(`package.json` or equivalent), payment or other third-party API SDKs among
|
|
105
|
+
them, CI config (`.github/workflows/`, etc.), and the **presence and names**
|
|
106
|
+
of `.env*`/config files as a signal that secrets live on disk here — never
|
|
107
|
+
their contents; a secret-bearing file's contents are exactly the kind of raw
|
|
108
|
+
value this wizard never reads. **Out of scope:** Antigravity's own history and the
|
|
109
|
+
local AKA store (that is the separate, consent-gated scan in steps 1/3) — no
|
|
110
|
+
historical read, and no question or other consent interaction of any kind.
|
|
111
|
+
|
|
112
|
+
The severity-floor default map (secret/pii/financial/phi/code_flaw/custom at
|
|
113
|
+
`warn`, code_context/config at `monitor` — the table step 2's start-light card
|
|
114
|
+
prints) is both the **floor** this check is measured against and its
|
|
115
|
+
**fallback**. From what you directly observe you may **tighten** individual
|
|
116
|
+
categories above that floor — raise the level, never lower one below it —
|
|
117
|
+
each tightened category carrying a one-line rationale naming the concrete
|
|
118
|
+
evidence you found, e.g.:
|
|
119
|
+
|
|
120
|
+
> Stripe + a `Customer` model here — financial → redact
|
|
121
|
+
|
|
122
|
+
Present the tightening on whichever recommended posture is about to render, the
|
|
123
|
+
same "recommended base + changed-packs overlay" shape step 4b's adjust fork
|
|
124
|
+
uses: the tightened categories raise, every other category keeps its existing
|
|
125
|
+
recommended level, each carrying its rationale line. Where you compose the view
|
|
126
|
+
yourself (the adjust fork, the calibrated result) this tightened recommendation
|
|
127
|
+
IS that view; where the view is a script's AKA_SHOW card (the step-2
|
|
128
|
+
start-light card, relayed per the execution contract), show the tightened
|
|
129
|
+
recommendation and its rationale lines adjacent to that card rather than
|
|
130
|
+
rewriting the card's own printed levels.
|
|
131
|
+
|
|
132
|
+
This tightening is a **display-time recommendation**: it shapes the recommended
|
|
133
|
+
posture the user reads, not a separate write. Persisting a tightened level happens
|
|
134
|
+
only where the wizard already writes a per-category override — the adjust fork's
|
|
135
|
+
`onboard.js --posture` write (step 4b), where the user picks each category's level
|
|
136
|
+
explicitly. The keep-defaults path writes the severity floor (`--floor`, step 2)
|
|
137
|
+
and the calibrated accept path applies the triage subprocess's saved plan
|
|
138
|
+
verbatim (`--confirmed --plan`, step 5); neither carries the tightening on its
|
|
139
|
+
own, so a tightened level the user wants persisted is chosen through the adjust
|
|
140
|
+
fork. Do **not** bolt on an extra `onboard.js --posture` overlay to auto-re-persist
|
|
141
|
+
the tightening across the other paths: it would overwrite — and so could silently
|
|
142
|
+
**downgrade** — a category the user had hardened out of band (a tightening is only
|
|
143
|
+
guaranteed to raise above the severity floor, not above the user's stored level),
|
|
144
|
+
with no downgrade-approval gate. So the tightening is not auto-persisted across
|
|
145
|
+
those paths — a tightened level the user wants kept is set through the adjust fork.
|
|
146
|
+
|
|
147
|
+
**When nothing in the working tree is inferable, change nothing.** Render the
|
|
148
|
+
recommended posture exactly as the static frame already gives it — no rationale
|
|
149
|
+
line and no tightened category (fail-open).
|
|
150
|
+
|
|
151
|
+
## 1. Offer the retroactive scan
|
|
152
|
+
|
|
153
|
+
Ask this **before** anything about detection posture — the posture
|
|
154
|
+
recommendation in step 4 is _derived from_ the answer to this question, so it
|
|
155
|
+
has to come first. Ask it per the execution contract's decision rules: a
|
|
156
|
+
conversational turn with numbered options, waiting for the user's reply.
|
|
157
|
+
|
|
158
|
+
**Disclose the model-API egress plainly before you show the options — this is what
|
|
159
|
+
the user is consenting to, so it must be visible before they choose.** State it in
|
|
160
|
+
your own words, without softening it: if they say yes, AKA scans the last 30 days
|
|
161
|
+
of Antigravity history, and to rate what it finds it **sends the raw, unmasked values —
|
|
162
|
+
including any secrets — to the model API through the `antigravity` CLI**. Name what
|
|
163
|
+
travels with each one: **its raw value, and about 120 characters of the
|
|
164
|
+
surrounding transcript text on either side** (any other secrets detected in
|
|
165
|
+
that window are masked; the rollout file's path stays local). That is real
|
|
166
|
+
network egress to the model provider (the same one your
|
|
167
|
+
Antigravity session already uses), not a purely local review. **A copy of each value
|
|
168
|
+
leaves the machine.** The rollouts those values came from stay on disk
|
|
169
|
+
untouched — nothing here removes them; that is the separate redaction step in
|
|
170
|
+
step 6. The judge's own conversation IS written to your local Antigravity
|
|
171
|
+
history under `~/.gemini/antigravity/brain/` — this host has no ephemeral
|
|
172
|
+
mode — and AKA deletes that conversation itself as soon as the run ends, best
|
|
173
|
+
effort; a killed process can leave it behind. That cleanup is a local-write
|
|
174
|
+
guard only, not network isolation. The findings are also
|
|
175
|
+
recorded, masked, to the local store. The grant is revocable from the
|
|
176
|
+
dashboard's **Settings → Historical access**, which stops future scans — it
|
|
177
|
+
cannot recall anything already sent. Do not present the options until you have
|
|
178
|
+
said this.
|
|
179
|
+
|
|
180
|
+
**Want me to look over what Antigravity has been up to?** — "I'll scan Antigravity's recent work — session rollouts, temp files, agent memory — and send what I find to the model to rate it, so I can tune what I bring you next."
|
|
181
|
+
|
|
182
|
+
Offer exactly two options:
|
|
183
|
+
|
|
184
|
+
1. **Yes, take a look** — "scan my real work here; raw findings go to the model to be rated, then tune what you bring me"
|
|
185
|
+
2. **Not now** — "start light and I'll learn as we go"
|
|
186
|
+
|
|
187
|
+
Choosing **Yes, take a look** records the same historical-review consent the wizard has
|
|
188
|
+
always recorded — the identical scope (which includes the model-API judgment disclosed
|
|
189
|
+
above), the one-time grant, and the same revocation semantics — so the simpler question
|
|
190
|
+
broadens nothing about what AKA may access. Those granular scope and revocation details
|
|
191
|
+
stay inspectable on request and in the dashboard, under **Settings → Historical access**,
|
|
192
|
+
whose own copy repeats the model-API disclosure.
|
|
193
|
+
|
|
194
|
+
## 2. Save the answer, then branch
|
|
195
|
+
|
|
196
|
+
Branch on the answer from step 1. On the **Yes, take a look** path the onboarding
|
|
197
|
+
writer runs, and it must run **before** the backfill (step 3), because the
|
|
198
|
+
backfill script reads `historicalAccess` from the saved settings to decide
|
|
199
|
+
whether it's allowed to run. Omitting `--policy` is deliberate — the old global
|
|
200
|
+
redact/warn toggle no longer drives enforcement (posture is per-category now);
|
|
201
|
+
its field is kept for backward compatibility but this wizard doesn't ask about
|
|
202
|
+
it.
|
|
203
|
+
|
|
204
|
+
**Branch on the choice:**
|
|
205
|
+
|
|
206
|
+
- **If the user chose "Yes, take a look"** — record the historical-review consent and
|
|
207
|
+
continue to step 3 (which runs the scan and leads to the calibrated result in
|
|
208
|
+
step 4). "Yes, take a look" maps to the existing full historical-review path — no
|
|
209
|
+
access is granted beyond what that path already granted:
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
node "${PLUGIN_ROOT}/scripts/onboard.js" --historical full
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
- **If the user chose "Not now"** — take the **start-light** path.
|
|
216
|
+
This path takes **zero historical access**: do **not** read any history, do
|
|
217
|
+
**not** run the backfill, and do **not** record consent — nothing about the
|
|
218
|
+
machine's past is touched.
|
|
219
|
+
Instead present the start-light posture card, write the posture the user picks
|
|
220
|
+
(this write **is** the applying frame — it stands in for step 5, which never
|
|
221
|
+
runs here because there is no scan plan to apply), and rejoin the spine at the
|
|
222
|
+
installed summary (step 6). **Skip steps 3, 4, and 5 entirely** — there is no
|
|
223
|
+
scan to triage, no calibrated result to confirm, and no suppression plan to
|
|
224
|
+
write. Do the following in order:
|
|
225
|
+
|
|
226
|
+
1. **Show the start-light card.** Run the start-light script and relay its
|
|
227
|
+
AKA_SHOW card per the execution contract — the
|
|
228
|
+
`● Starting light — your detection categories` heading, the full 8-pack ×
|
|
229
|
+
4-level default posture table, the per-pack rationale, and the re-tune
|
|
230
|
+
hint, pasted between the markers exactly as printed, fence included. It
|
|
231
|
+
reads no history and writes nothing; it only prints the card
|
|
232
|
+
(the severity-floor default map — secret, pii, financial, phi, code_flaw, custom at
|
|
233
|
+
`warn`; code_context, config at `monitor`).
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
node "${PLUGIN_ROOT}/scripts/start-light.js"
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
2. **Confirm or adjust.** Ask — per the execution contract's decision rules —
|
|
240
|
+
whether to keep the recommended defaults or tune individual packs:
|
|
241
|
+
|
|
242
|
+
**Set your detection categories** — "Keep the defaults I'd recommend, or adjust any of them?"
|
|
243
|
+
|
|
244
|
+
1. **Keep defaults** _(recommended)_ — "the careful defaults shown above"
|
|
245
|
+
2. **Adjust** — "change one or more levels, keep the rest as I recommend"
|
|
246
|
+
|
|
247
|
+
If they choose **Adjust**, ask again — same decision rules — to collect the
|
|
248
|
+
new level (monitor/warn/redact/block) for each pack they want to change,
|
|
249
|
+
then merge those overrides over the severity-floor defaults to form the
|
|
250
|
+
full 8-pack map.
|
|
251
|
+
|
|
252
|
+
3. **Write the chosen posture.** The default map is the severity floor,
|
|
253
|
+
so when the user keeps the defaults, write the floor directly; when they
|
|
254
|
+
adjusted packs, write the merged 8-pack map:
|
|
255
|
+
|
|
256
|
+
```bash
|
|
257
|
+
# Kept the recommended defaults
|
|
258
|
+
node "${PLUGIN_ROOT}/scripts/onboard.js" --floor
|
|
259
|
+
|
|
260
|
+
# Adjusted one or more packs — <json> is the merged 8-pack map
|
|
261
|
+
node "${PLUGIN_ROOT}/scripts/onboard.js" --posture '<json>'
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
Either write prints only `✓ Set all K detection categories` (the `--floor`
|
|
265
|
+
write appends ` — safe defaults`) — which is the honest confirmation here,
|
|
266
|
+
because nothing was scanned or suppressed. Show that line to the user; do
|
|
267
|
+
**not** invent a dismissed count or any calibration counts.
|
|
268
|
+
|
|
269
|
+
4. **Rejoin the spine at the installed summary (step 6).** Continue to step 6
|
|
270
|
+
to show the installed summary and hand off to the dashboard, using honest
|
|
271
|
+
no-scan copy. No scan ran, so there is **no surfaced count** — call
|
|
272
|
+
`firstrun.js` with **no `--surfaced` flag** (the same floor-fallback rule
|
|
273
|
+
step 6 already follows when no calibration frame was emitted). Step 7
|
|
274
|
+
then runs as written.
|
|
275
|
+
|
|
276
|
+
## 3. Run the evidence triage — off-transcript judgment, nothing written yet
|
|
277
|
+
|
|
278
|
+
**Model-judge consent — a distinct opt-in, asked here before the pipe.** The
|
|
279
|
+
false-positive/severity judgment runs by sending each finding to the model API
|
|
280
|
+
through `antigravity`. That is a separate egress from the historical-read consent
|
|
281
|
+
collected in step 1 (which only let AKA _read_ the local rollouts), so it needs
|
|
282
|
+
its own explicit grant. Before running the pipe, restate plainly what leaves the
|
|
283
|
+
machine (the step-1 disclosure's payload: each raw value plus its masked context
|
|
284
|
+
window; the file path stays local), then ask as a normal conversational turn
|
|
285
|
+
with numbered options — and present both options flat: this grant sends the
|
|
286
|
+
user's data off the machine, so do **not** mark either one recommended.
|
|
287
|
+
|
|
288
|
+
**Send findings to the model to sort real leaks from noise?** — "I'll send each
|
|
289
|
+
detected value, plus a bit of surrounding context with any secrets in it masked,
|
|
290
|
+
to the model to tell real leaks from routine noise. The file path stays local.
|
|
291
|
+
This consent is saved machine-wide in AKA's settings, so it also covers the
|
|
292
|
+
same triage step in AKA's other harness plugins on this machine — revoke it
|
|
293
|
+
anytime from the dashboard."
|
|
294
|
+
|
|
295
|
+
1. **Yes, send them** — "let the model triage what I found"
|
|
296
|
+
2. **No, keep it local** — "skip the model triage and start from the safe defaults"
|
|
297
|
+
|
|
298
|
+
**Branch on the choice:**
|
|
299
|
+
|
|
300
|
+
- **If the user chose "Yes, send them"** — record the model-judge consent, then
|
|
301
|
+
run the pipe below:
|
|
302
|
+
|
|
303
|
+
```bash
|
|
304
|
+
node "${PLUGIN_ROOT}/scripts/onboard.js" --model-judge-consent
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
- **If the user chose "No, keep it local"** — do **not** run the pipe. The judge
|
|
308
|
+
refuses to run without consent (it would only print a clean skip line and a
|
|
309
|
+
zero-count frame), so there is no calibrated plan to confirm. Fall back to the
|
|
310
|
+
conservative severity floor exactly as step 2's start-light path does — write
|
|
311
|
+
the floor, tell the user the model triage was skipped, and continue to step 6
|
|
312
|
+
with **no `--surfaced` flag**:
|
|
313
|
+
|
|
314
|
+
```bash
|
|
315
|
+
node "${PLUGIN_ROOT}/scripts/onboard.js" --floor
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
Pipe the backfill's triage stream straight into the `apply-suppressions`
|
|
319
|
+
adapter in **PREVIEW** mode (no `--confirmed`):
|
|
320
|
+
|
|
321
|
+
```bash
|
|
322
|
+
node "${PLUGIN_ROOT}/scripts/backfill.js" --triage | node "${PLUGIN_ROOT}/scripts/apply-suppressions.js"
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
The backfill sweeps prior Antigravity CLI conversation transcripts (last 30
|
|
326
|
+
days, all conversations) and streams one masked-plus-raw triage hit per line;
|
|
327
|
+
masked findings are recorded to the local store as a side effect. The adapter
|
|
328
|
+
runs the false-positive/severity **judgment in separate `agy -p` subprocesses
|
|
329
|
+
that send each hit's raw value and masked context window — never its source
|
|
330
|
+
path — to the model API** (a large history is split into several batches; each
|
|
331
|
+
run persists a conversation under `~/.gemini/antigravity/brain/`, which AKA
|
|
332
|
+
then deletes best effort — this host has no ephemeral mode), then prints back a
|
|
333
|
+
**raw-free plan** you can safely show the user:
|
|
334
|
+
the calibrated-result card (the real-count headline and the recommended posture),
|
|
335
|
+
the per-category reasoning, the masked false positives it would suppress, any
|
|
336
|
+
categories it skipped, and its notes.
|
|
337
|
+
|
|
338
|
+
The preview also **persists that exact raw-free plan to a temp file and prints
|
|
339
|
+
its path** — a line beginning `Plan saved to: <path>`. Capture that path: step 5
|
|
340
|
+
applies **this saved plan verbatim**, so the confirm step performs no second scan
|
|
341
|
+
and no second judgment. (The plan file carries only masked/fingerprint/enum data;
|
|
342
|
+
it is deleted after a successful apply.)
|
|
343
|
+
|
|
344
|
+
Alongside the human copy, the preview also emits a **machine-readable calibration
|
|
345
|
+
frame** — a single JSON block delimited by `<<<AKA_FRAME_JSON` … `AKA_FRAME_JSON>>>`
|
|
346
|
+
carrying the raw-free calibration counts and categories, plus (when the scan
|
|
347
|
+
surfaced any) a `maskedFindings` array of raw-free secret-leak summaries. Do
|
|
348
|
+
**not** show this block to the user (it is additive to the human copy above).
|
|
349
|
+
Capture its `counts.important` value — the **surfaced count** — and pass it to the
|
|
350
|
+
first-run summary in step 6 as `--surfaced <count>` — but **only when the preview
|
|
351
|
+
also printed a `Plan saved to:` path** (a real calibrated plan to confirm in step
|
|
352
|
+
4). The `Plan saved to:` line is the completion signal: a preview that omits it did
|
|
353
|
+
not calibrate a plan you can confirm. The fallback branches below carry no
|
|
354
|
+
surfaced count; the scan-ran-clean empty state (a scan that completed but
|
|
355
|
+
surfaced nothing) emits a zero-count frame but **no plan path**, so it too routes
|
|
356
|
+
to the floor branch below rather than step 4.
|
|
357
|
+
|
|
358
|
+
Also **retain the block's full text verbatim** (not just the counts you read out
|
|
359
|
+
of it) — step 6's "Review leaked keys" branch feeds this same text to the
|
|
360
|
+
secret-leak remediation entry, which reads its own `maskedFindings` from it,
|
|
361
|
+
and step 4's finding narration and step 6's secret-leak narration (both below)
|
|
362
|
+
read the same `maskedFindings` array off it too. When present, the block's
|
|
363
|
+
`falsePositivePatterns` array is what step 4's fixture/exception offer (below)
|
|
364
|
+
names its pattern and count from — never invent either off-signal.
|
|
365
|
+
|
|
366
|
+
Everything you show the user in step 4 comes from **this command's output**. You
|
|
367
|
+
never read the raw finding values yourself — do not echo, quote, or reconstruct
|
|
368
|
+
them; the judge subprocesses send them to the model API and return only the
|
|
369
|
+
raw-free plan, so they never enter this conversation.
|
|
370
|
+
|
|
371
|
+
**Failed or truncated triage — never proceed silently (fallback).** If this
|
|
372
|
+
command exits non-zero, or the adapter reports a truncated / sentinel-less
|
|
373
|
+
stream, the calibration could **not** complete. Do not guess a posture and do
|
|
374
|
+
not leave setup half-applied. Apply the conservative severity floor, **tell the
|
|
375
|
+
user it happened**, and continue to step 6:
|
|
376
|
+
|
|
377
|
+
```bash
|
|
378
|
+
node "${PLUGIN_ROOT}/scripts/onboard.js" --floor
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
Say plainly: the historical scan couldn't finish, so AKA is starting from the
|
|
382
|
+
conservative severity floor (high-impact categories at `warn`, observe-only at
|
|
383
|
+
`monitor`) instead of a calibrated posture, and it can be re-run any time with
|
|
384
|
+
the aka-setup skill.
|
|
385
|
+
|
|
386
|
+
**Nothing to calibrate.** A scan that **completes but surfaces nothing** prints
|
|
387
|
+
the honest **scan-ran-clean** card — `I looked over Antigravity's recent work —
|
|
388
|
+
nothing needs your attention right now. You're starting clean; here's what I'd
|
|
389
|
+
recommend:` over the recommended posture — with a zero-count calibration frame
|
|
390
|
+
(its `counts.important` is `0`) and **no `Plan saved to:` path**. A machine with
|
|
391
|
+
no history to scan instead prints the no-history card (`Nothing to learn from
|
|
392
|
+
yet — Antigravity hasn't left any work on this machine.` over the start-light table),
|
|
393
|
+
and a scan skipped for lack of consent prints `I didn't review anything —
|
|
394
|
+
historical access wasn't granted.`. In every one of these cases there's no
|
|
395
|
+
evidence to calibrate from and no plan to confirm: show the card the adapter
|
|
396
|
+
printed, take the floor branch (`onboard.js --floor`), tell the user the scan
|
|
397
|
+
found nothing to calibrate from, and skip to step 6 (with **no `--surfaced`**,
|
|
398
|
+
the floor-fallback rule there — nothing was surfaced to carry over). Do **not**
|
|
399
|
+
continue to step 4.
|
|
400
|
+
|
|
401
|
+
Otherwise (the preview printed a `Plan saved to:` path) continue to step 4.
|
|
402
|
+
|
|
403
|
+
## 4. Show the calibrated result and get explicit confirmation — before any write
|
|
404
|
+
|
|
405
|
+
The preview output is raw-free. Lead with the **calibrated-result card** it
|
|
406
|
+
printed and show it in full:
|
|
407
|
+
|
|
408
|
+
1. **The calibrated headline.** The `I went through Antigravity's recent work — N
|
|
409
|
+
detections, M results worth a look.` line — every count templated over the
|
|
410
|
+
real scan (surfaced findings are the `M results` worth a look; the rest are
|
|
411
|
+
routine noise a plain scanner would have screamed about). Show it verbatim;
|
|
412
|
+
never substitute a demo number.
|
|
413
|
+
2. **The recommended posture.** The condensed one-row-per-pack recommended view
|
|
414
|
+
the card printed — the level AKA would set for each category. Show it in full.
|
|
415
|
+
- **Surface the downgrades the preview flags — this is not optional.** For the
|
|
416
|
+
recommended posture it is about to write, the preview compares each category
|
|
417
|
+
against its stored setting and flags any that would be **LOWERED** from a
|
|
418
|
+
stronger existing one (e.g. an existing `block`/`redact` dropping to
|
|
419
|
+
`warn`/`monitor`), printing a `WARNING` line summarizing them. Call these out
|
|
420
|
+
prominently: a user who hardened a category must **explicitly approve weakening
|
|
421
|
+
it** before applying.
|
|
422
|
+
3. **The false positives to be suppressed (the human gate).** The masked value,
|
|
423
|
+
rule, and masked context for each detection the writeback would suppress —
|
|
424
|
+
the routine noise being dismissed. This is the checkpoint that stops a genuine
|
|
425
|
+
secret being silenced: the user reads the masked evidence and approves it.
|
|
426
|
+
4. **Explain what surfaced, in plain language.** When the frame carries
|
|
427
|
+
`maskedFindings`, walk through them — what each one is, where it showed up,
|
|
428
|
+
and why it matters — grounded entirely in that array: every count you speak
|
|
429
|
+
equals the frame's own count for it (`counts.important`/`counts.total`, or
|
|
430
|
+
a specific finding kind's count), and every value you reference appears
|
|
431
|
+
masked, exactly as the frame gives it — never a raw value, never an
|
|
432
|
+
invented one. This is an actual explanation of the known findings, not a
|
|
433
|
+
restatement of the headline's counts. When the frame carries no
|
|
434
|
+
`maskedFindings` (nothing surfaced, or a fallback floor ran), skip this —
|
|
435
|
+
the calibrated-result card already said so; do not invent narration over a
|
|
436
|
+
missing signal.
|
|
437
|
+
5. **Offer an exception for a grounded false-positive pattern.** When the
|
|
438
|
+
frame carries `falsePositivePatterns`, name each group's pattern and count
|
|
439
|
+
**strictly from that signal** — never invent a pattern name or fabricate a
|
|
440
|
+
count. For each group, ask — per the execution contract's decision rules —
|
|
441
|
+
whether to set a pre-filled exception, with a duration choice (the exception
|
|
442
|
+
scope axis — `once` / `temporary` / `permanent`):
|
|
443
|
+
|
|
444
|
+
**Make an exception for `<pattern>` (×N)?** — "This `<pattern>` looks like a
|
|
445
|
+
test fixture — want me to set an exception so it stops popping up?"
|
|
446
|
+
|
|
447
|
+
1. **Once** — just this once — expires in 30 minutes
|
|
448
|
+
2. **Temporary** — for a set window, then I'll check it again
|
|
449
|
+
3. **Permanent** — stays until you revoke it
|
|
450
|
+
4. **Not now** — skip — I won't write anything
|
|
451
|
+
|
|
452
|
+
**Temporary needs a concrete window.** `once` and `permanent` fully determine
|
|
453
|
+
the scope on their own, but `temporary` does not — resolving it into the
|
|
454
|
+
stored `{scope, expiresAt, maxUses}` triple requires an actual duration, and
|
|
455
|
+
you must **never** invent or default one. When the user picks **Temporary**,
|
|
456
|
+
follow up with a second question that offers concrete windows only
|
|
457
|
+
— `30m` / `1h` / `24h` (the exception scope resolver accepts `<n>m`/`<n>h`,
|
|
458
|
+
capped at 24h; a longer bypass is a `permanent` grant, not a forgotten timer)
|
|
459
|
+
— and resolve the exact chosen string through that resolver. **Once** and
|
|
460
|
+
**Permanent** take no follow-up.
|
|
461
|
+
|
|
462
|
+
Accepting surfaces the exact pre-filled exception — one **per distinct value
|
|
463
|
+
identity** (`ruleId`/`valueFingerprint`/`keyVersion`) at the chosen
|
|
464
|
+
`{scope, expiresAt, maxUses}` — for review, and the marked pattern is
|
|
465
|
+
suppressed as part of the calibration plan confirmed below (the same store
|
|
466
|
+
the aka-exceptions skill reads). A group whose displayed pattern covers more
|
|
467
|
+
than one distinct value surfaces one exception per distinct value — never a
|
|
468
|
+
single grant collapsing them — and a value missing its exact identity is not
|
|
469
|
+
offered for. Declining surfaces nothing; this offer is separate from the
|
|
470
|
+
calibration plan's suppressions confirmed below, so declining here changes
|
|
471
|
+
nothing about that confirmation. When the frame carries no
|
|
472
|
+
`falsePositivePatterns` (nothing was marked a likely false positive, or the
|
|
473
|
+
scan was declined), skip this entirely — no offer, nothing invented
|
|
474
|
+
(fail-open).
|
|
475
|
+
|
|
476
|
+
Then ask — per the execution contract's decision rules, never answering for the
|
|
477
|
+
user — to confirm:
|
|
478
|
+
|
|
479
|
+
**Want me to apply this?** — "I'll set these levels and suppress the false
|
|
480
|
+
positives above."
|
|
481
|
+
|
|
482
|
+
1. **Yes, apply** _(recommended)_ — write the posture and suppressions exactly as
|
|
483
|
+
previewed.
|
|
484
|
+
2. **Adjust a category** — "change one or more first; keep the rest as I
|
|
485
|
+
recommend"
|
|
486
|
+
|
|
487
|
+
Do **not** proceed until the user picks one. On **Yes, apply**, continue to
|
|
488
|
+
step 5 and apply the previewed plan verbatim — that is the confirm spine,
|
|
489
|
+
unchanged. On **Adjust a category**, take the **adjust fork** (step 4b), which
|
|
490
|
+
applies within the fork and rejoins the spine at the installed summary (step 6).
|
|
491
|
+
|
|
492
|
+
## 4b. Adjust a category — the override fork
|
|
493
|
+
|
|
494
|
+
The **adjust base is the calibrated recommended posture the preview just
|
|
495
|
+
printed** — the condensed one-row-per-pack view from step 4, not the cold-start
|
|
496
|
+
severity floor. The user changes the packs they want and keeps the rest as
|
|
497
|
+
recommended.
|
|
498
|
+
|
|
499
|
+
1. **Collect the changes.** Ask — per the execution contract's decision rules —
|
|
500
|
+
which packs to change and to which level (monitor/warn/redact/block), one
|
|
501
|
+
clear numbered-option question at a time.
|
|
502
|
+
|
|
503
|
+
2. **Show the adjust-confirm table.** Compose the merged 8-pack map — the
|
|
504
|
+
recommended base with the user's picks overlaid — and render the adjust-confirm
|
|
505
|
+
card by passing the calibrated recommended posture as `--recommended` and that
|
|
506
|
+
merged map as `--posture`. Relay its AKA_SHOW region per the execution
|
|
507
|
+
contract — the fenced `category │ recommended │ yours` table, pasted between
|
|
508
|
+
the markers exactly as printed (it is space-aligned monospace; do **not** add
|
|
509
|
+
another code fence, strip the fence, or reformat it):
|
|
510
|
+
|
|
511
|
+
```bash
|
|
512
|
+
node "${PLUGIN_ROOT}/scripts/start-light.js" --adjust-confirm --recommended '<recommended-json>' --posture '<merged-json>' --current '<current-json>'
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
`<recommended-json>` is the calibrated recommended posture the preview printed
|
|
516
|
+
(the adjust base) — so the `recommended` column shows each pack's calibrated
|
|
517
|
+
level, and a pack calibration escalated above the floor never renders as a
|
|
518
|
+
spurious change. `<merged-json>` is the full 8-pack map — that same recommended
|
|
519
|
+
base with the user's overrides overlaid — so a changed pack reads as a different
|
|
520
|
+
`yours` value and every untouched pack repeats its recommended level.
|
|
521
|
+
`<current-json>` is the `current` object from the plan file at the path step 3
|
|
522
|
+
printed (`Plan saved to: <path>`) — the store's per-category action at preview
|
|
523
|
+
time, the baseline the downgrade check compares against. Pass it verbatim; do
|
|
524
|
+
not retype or summarize it.
|
|
525
|
+
|
|
526
|
+
3. **Surface any downgrade — the card computes this, you do not.** With
|
|
527
|
+
`--current` passed, the card itself appends the `WARNING: N categories … would
|
|
528
|
+
be LOWERED from a stronger existing setting` footer whenever a pick weakens
|
|
529
|
+
enforcement — the same rule and the same wording as the confirm gate above,
|
|
530
|
+
from the same code. Show the card in full, footer included, and when that
|
|
531
|
+
footer is present get explicit approval before saving. Never let an enforcement
|
|
532
|
+
downgrade through without the user having seen it.
|
|
533
|
+
|
|
534
|
+
4. **Save or back out.** Ask — per the execution contract's decision rules —
|
|
535
|
+
with **N** the number of packs the user changed and **M** the number kept as
|
|
536
|
+
recommended (`M = 8 − N`), both real — never a placeholder:
|
|
537
|
+
|
|
538
|
+
**Save your adjustments?**
|
|
539
|
+
|
|
540
|
+
1. **Save adjusted — N changed, M as recommended** — apply with the adjusted
|
|
541
|
+
posture.
|
|
542
|
+
2. **Back to recommended** — discard the changes and apply the recommended
|
|
543
|
+
posture instead.
|
|
544
|
+
|
|
545
|
+
5. **On "Save adjusted" — produce the applying frame here, carrying the adjusted
|
|
546
|
+
posture, then rejoin the spine at the installed summary (step 6).** This fork
|
|
547
|
+
applies within itself and **stands in for step 5**, so step 5 never runs on
|
|
548
|
+
this path. First apply the previewed plan with the **unchanged confirm spine**,
|
|
549
|
+
so the reviewed false positives are dismissed and the recommended base is
|
|
550
|
+
written (the reviewed evidence packs overwrite; the severity floor fill-gaps the
|
|
551
|
+
rest, so a pack hardened out of band is never downgraded):
|
|
552
|
+
|
|
553
|
+
```bash
|
|
554
|
+
node "${PLUGIN_ROOT}/scripts/apply-suppressions.js" --confirmed --plan <path>
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
If that `--confirmed` run exits non-zero (or `--plan` is missing/unreadable),
|
|
558
|
+
handle it exactly as step 5 does: tell the user the write did not complete, fall
|
|
559
|
+
back to the floor (`onboard.js --floor`), and continue to step 6. Do **not** run
|
|
560
|
+
the overlay below on a failed spine — nothing was written, so there is no
|
|
561
|
+
recommended base to overlay the changes onto.
|
|
562
|
+
|
|
563
|
+
Then overwrite **only the packs the user changed** with their chosen levels:
|
|
564
|
+
|
|
565
|
+
```bash
|
|
566
|
+
node "${PLUGIN_ROOT}/scripts/onboard.js" --posture '<changed-packs-json>'
|
|
567
|
+
```
|
|
568
|
+
|
|
569
|
+
`<changed-packs-json>` carries **only** the packs the user adjusted (not the
|
|
570
|
+
full 8-pack map), so the packs kept as recommended keep the fill-gaps-safe
|
|
571
|
+
values the spine wrote and only the user's explicit, downgrade-approved changes
|
|
572
|
+
overwrite.
|
|
573
|
+
|
|
574
|
+
If that overlay exits non-zero, the spine already wrote the recommended base, so
|
|
575
|
+
the store holds a valid posture — but **not** the user's overrides. Tell the user
|
|
576
|
+
their adjustments did not save and the store holds the recommended posture, then
|
|
577
|
+
continue to step 6. Do **not** report the adjusted posture as saved on a failed
|
|
578
|
+
overlay.
|
|
579
|
+
|
|
580
|
+
On success, present the applying-frame confirmation the **spine** printed —
|
|
581
|
+
`✓ Set all 8 detection categories · set aside N routine results · Ready: …` —
|
|
582
|
+
the store now holds the adjusted posture. The overlay's own smaller
|
|
583
|
+
`✓ Set all N detection categories` line (the count of just the changed packs)
|
|
584
|
+
is bookkeeping — **do not show it**; the applying frame reports the full
|
|
585
|
+
8-pack posture. Then continue to step 6.
|
|
586
|
+
|
|
587
|
+
**On "Back to recommended"** — take the **Yes, apply** path instead: continue
|
|
588
|
+
to step 5 and apply the previewed plan verbatim with no override.
|
|
589
|
+
|
|
590
|
+
Do **not** write anything until the user has explicitly confirmed at step 4
|
|
591
|
+
(Yes, apply) or saved at step 4b (Save adjusted).
|
|
592
|
+
|
|
593
|
+
## 5. Write the posture and suppressions
|
|
594
|
+
|
|
595
|
+
On confirmation, run the adapter again with `--confirmed --plan <path>`, passing
|
|
596
|
+
the **plan-file path the preview printed in step 3** (`Plan saved to: <path>`). It
|
|
597
|
+
reads that saved plan back and applies it **exactly as previewed** — establishing
|
|
598
|
+
the **full 8-pack posture** the recommended view showed (the reviewed
|
|
599
|
+
evidence packs overwrite; the conservative severity floor fill-gaps the remaining
|
|
600
|
+
packs, so a pack the user had already hardened out of band is never downgraded) and
|
|
601
|
+
writing one 30-day suppression per confirmed false positive **without re-running the
|
|
602
|
+
backfill or the judge**. There is deliberately **no `backfill.js` pipe here**:
|
|
603
|
+
re-scanning and re-judging would produce a fresh, non-deterministic plan and
|
|
604
|
+
silently defeat the human gate the user just approved.
|
|
605
|
+
|
|
606
|
+
The posture overwrite and the suppression writes are applied as a **single
|
|
607
|
+
all-or-nothing transaction**: a mid-batch failure rolls back the posture change
|
|
608
|
+
too, so the store is never left half-applied. That is why the floor fallback below
|
|
609
|
+
is safe — a non-zero exit means **nothing** persisted, so re-applying the
|
|
610
|
+
conservative floor cannot collide with a partially-written posture.
|
|
611
|
+
|
|
612
|
+
```bash
|
|
613
|
+
node "${PLUGIN_ROOT}/scripts/apply-suppressions.js" --confirmed --plan <path>
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
The script prints the applying confirmation — `✓ Set all K detection categories
|
|
617
|
+
· set aside N routine results · Ready: …` — with both counts threaded from the
|
|
618
|
+
real write. Show that line to the user.
|
|
619
|
+
|
|
620
|
+
If `--plan` is missing or the file is unreadable/invalid, the adapter **fails loud
|
|
621
|
+
(non-zero) and writes nothing** — it never falls back to a re-judge. Treat that
|
|
622
|
+
like the `--confirmed` failure below: tell the user the write did not complete,
|
|
623
|
+
fall back to the floor, and continue to step 6.
|
|
624
|
+
|
|
625
|
+
If the `--confirmed` run exits non-zero, tell the user the write did not
|
|
626
|
+
complete, fall back to the floor (`onboard.js --floor`), and continue to step 6
|
|
627
|
+
so setup still finishes.
|
|
628
|
+
|
|
629
|
+
## 6. Show the installed summary and hand off to the dashboard
|
|
630
|
+
|
|
631
|
+
Run the first-run script and relay its **install-complete summary** AKA_SHOW
|
|
632
|
+
region per the execution contract (live findings/recommendation counts, the
|
|
633
|
+
health score, and the per-category posture just written or floored). The
|
|
634
|
+
script wraps that summary in a Markdown code fence; paste it between the
|
|
635
|
+
markers exactly as printed and do **not** add another code fence, strip the
|
|
636
|
+
fence, or reformat it (it is space-aligned monospace that Markdown would
|
|
637
|
+
otherwise collapse).
|
|
638
|
+
|
|
639
|
+
Pass the **surfaced count** captured from step 3's calibration frame
|
|
640
|
+
(`counts.important`) as `--surfaced <count>` — this is the 'N worth a look' figure
|
|
641
|
+
the script emits in its own machine-readable handoff payload — but only when step 3
|
|
642
|
+
carried a surfaced count forward (it printed a `Plan saved to:` path). If the
|
|
643
|
+
calibration fell back to the floor (no plan path in step 3 — a fallback branch, or
|
|
644
|
+
the scan-ran-clean empty state whose zero-count frame carries nothing to look at),
|
|
645
|
+
**omit `--surfaced` entirely** — the script then withholds that payload rather than
|
|
646
|
+
fabricating a count.
|
|
647
|
+
|
|
648
|
+
Alongside it, pass the **surfaced live-key count** — the number of surfaced
|
|
649
|
+
live-key secret findings, which is the length of the calibration frame's
|
|
650
|
+
`maskedFindings` array (absent ⇒ 0) — as `--live-keys <count>`. This is the
|
|
651
|
+
narrower secret subset of the surfaced count; it gates the remediation
|
|
652
|
+
chain-entry the handoff offers, so a calibration that surfaced only non-secret
|
|
653
|
+
findings passes `--live-keys 0` and offers no remediation.
|
|
654
|
+
|
|
655
|
+
When `--surfaced` is passed, the script appends that handoff payload as a single
|
|
656
|
+
JSON block delimited by `<<<AKA_FRAME_JSON` … `AKA_FRAME_JSON>>>` after the fenced
|
|
657
|
+
card. Like step 3's calibration frame, do **not** show this block to the user — it
|
|
658
|
+
is additive and machine-only; only the fenced install summary above is
|
|
659
|
+
user-facing.
|
|
660
|
+
|
|
661
|
+
```bash
|
|
662
|
+
node "${PLUGIN_ROOT}/scripts/firstrun.js" --surfaced <count> --live-keys <count>
|
|
663
|
+
```
|
|
664
|
+
|
|
665
|
+
**Then hand off to the dashboard.** When the payload carries a positive
|
|
666
|
+
`worthALook` count, ask explicitly — per the execution contract's decision rules
|
|
667
|
+
— using that count for `N`:
|
|
668
|
+
|
|
669
|
+
**N worth a look — want to see them in the browser?**
|
|
670
|
+
|
|
671
|
+
1. **Review leaked keys** — "let's deal with the exposed keys I found" —
|
|
672
|
+
_(offer this option first only when the payload's `options` include
|
|
673
|
+
`enter-remediation`, i.e. `liveKeys > 0`)_; entering it starts the
|
|
674
|
+
secret-leak remediation chain on the surfaced live keys. This composes with —
|
|
675
|
+
never replaces — the dashboard handoff below, so both stay reachable.
|
|
676
|
+
2. **Open dashboard** — "open the local dashboard on what I found"
|
|
677
|
+
3. **Not now** — "stay here — you can open it anytime"
|
|
678
|
+
|
|
679
|
+
Use the payload's `worthALook` value for `N` verbatim — do not invent or round it.
|
|
680
|
+
Offer **Review leaked keys** exactly when the payload's `options` carry the
|
|
681
|
+
`enter-remediation` entry (never otherwise); the **Open dashboard** / **Not now**
|
|
682
|
+
handoff is always present. If the payload was withheld (the floor fallback, or
|
|
683
|
+
nothing surfaced), skip this handoff question rather than inventing a count.
|
|
684
|
+
|
|
685
|
+
**If they choose "Review leaked keys"** — run the secret-leak remediation entry's
|
|
686
|
+
**present** mode, feeding it the calibration frame block you captured in step 3
|
|
687
|
+
(the same text `maskedFindings` came from) on stdin:
|
|
688
|
+
|
|
689
|
+
```bash
|
|
690
|
+
node "${PLUGIN_ROOT}/scripts/remediate.js" <<'AKA_FRAME'
|
|
691
|
+
<the <<<AKA_FRAME_JSON … AKA_FRAME_JSON>>> block captured in step 3, verbatim>
|
|
692
|
+
AKA_FRAME
|
|
693
|
+
```
|
|
694
|
+
|
|
695
|
+
It prints the decision as human-facing text, then a machine-readable block
|
|
696
|
+
delimited by `<<<AKA_FRAME_JSON` … `AKA_FRAME_JSON>>>` carrying the same decision
|
|
697
|
+
structured (do **not** show that block to the user). The human text has three
|
|
698
|
+
parts, all of which you **show to the user verbatim, in order**:
|
|
699
|
+
|
|
700
|
+
1. the templated count line ("I found N exposed secret keys sitting in old
|
|
701
|
+
transcripts."),
|
|
702
|
+
2. the fenced finding table (provider, masked token, where, state), and
|
|
703
|
+
3. inside that same fence, a most-exposed-first recommendation line and a
|
|
704
|
+
secret-scan chaining line.
|
|
705
|
+
|
|
706
|
+
This entire human-text block is the entry's AKA_SHOW region — relay it per the
|
|
707
|
+
execution contract, pasting it between the markers exactly as printed — do not
|
|
708
|
+
drop the recommendation or chaining lines, and do not paraphrase.
|
|
709
|
+
|
|
710
|
+
Alongside that fenced block, explain the findings in plain language grounded
|
|
711
|
+
in the same `maskedFindings` array the block came from — what each finding is
|
|
712
|
+
and why it matters, not a bare recital of the count line above it. The same
|
|
713
|
+
grounding discipline as step 4's narration applies here: every count you
|
|
714
|
+
speak matches the frame's own count, and every value you reference stays
|
|
715
|
+
masked. With no `maskedFindings` present there is nothing to narrate beyond
|
|
716
|
+
the count line and table already shown — do not invent an explanation.
|
|
717
|
+
|
|
718
|
+
Then ask — per the execution contract's decision rules — offering exactly these
|
|
719
|
+
four options, in order (each option's label maps to the `--option` id shown in
|
|
720
|
+
parentheses):
|
|
721
|
+
|
|
722
|
+
1. **Redact + rotation checklist** (`redact-rotation-checklist`)
|
|
723
|
+
2. **Redact only** (`redact-only`)
|
|
724
|
+
3. **Set 'secret' to redact** (`set-secret-redact`)
|
|
725
|
+
4. **Leave** (`leave`)
|
|
726
|
+
|
|
727
|
+
**If they chose "Redact + rotation checklist" or "Redact only"** — before running
|
|
728
|
+
the route, ask a second question presenting the standing-posture prompt,
|
|
729
|
+
offering exactly these four options, in order (each option's label maps to the
|
|
730
|
+
`--posture` level in parentheses):
|
|
731
|
+
|
|
732
|
+
**Set the 'secret' detection level**
|
|
733
|
+
|
|
734
|
+
1. **Redact** (`redact`)
|
|
735
|
+
2. **Warn** (`warn`)
|
|
736
|
+
3. **Block** (`block`)
|
|
737
|
+
4. **Monitor** (`monitor`)
|
|
738
|
+
|
|
739
|
+
Then run the entry's **route** mode ONCE with the chosen redact option's id AND
|
|
740
|
+
the chosen posture level, feeding it the SAME calibration frame block again on
|
|
741
|
+
stdin:
|
|
742
|
+
|
|
743
|
+
```bash
|
|
744
|
+
node "${PLUGIN_ROOT}/scripts/remediate.js" --option <id> --posture <level> <<'AKA_FRAME'
|
|
745
|
+
<the same block>
|
|
746
|
+
AKA_FRAME
|
|
747
|
+
```
|
|
748
|
+
|
|
749
|
+
Never run the route a second time for this choice — a repeat call would strike
|
|
750
|
+
the already-redacted keys again and corrupt the reported count. Show its printed
|
|
751
|
+
result verbatim, in order. For "Redact only" that is the redaction confirmation
|
|
752
|
+
then the standing-posture confirmation. For "Redact + rotation checklist" it is
|
|
753
|
+
the standing-posture confirmation then the resolved rotation-checklist summary —
|
|
754
|
+
which reports the redaction itself, so the script does not print a separate
|
|
755
|
+
redaction confirmation ahead of it.
|
|
756
|
+
|
|
757
|
+
**If they chose "Set 'secret' to redact" or "Leave"** — run the entry's **route**
|
|
758
|
+
mode with the chosen option's id (the id in parentheses above, e.g. **Leave** →
|
|
759
|
+
`leave`), feeding it the SAME calibration frame block again on stdin:
|
|
760
|
+
|
|
761
|
+
```bash
|
|
762
|
+
node "${PLUGIN_ROOT}/scripts/remediate.js" --option <id> <<'AKA_FRAME'
|
|
763
|
+
<the same block>
|
|
764
|
+
AKA_FRAME
|
|
765
|
+
```
|
|
766
|
+
|
|
767
|
+
Show its printed result verbatim — a standing-posture confirmation, or (choosing
|
|
768
|
+
"Leave") a plain note that nothing changed. This entry reads its findings from the
|
|
769
|
+
calibration frame alone and holds no wizard state of its own, so it works
|
|
770
|
+
identically from any caller.
|
|
771
|
+
|
|
772
|
+
## 7. Offer the AKA CLI + local dashboard (opt-in)
|
|
773
|
+
|
|
774
|
+
Now that the plugin is set up, offer the optional **AKA CLI + local dashboard** —
|
|
775
|
+
a richer, still-fully-local surface over the same `~/.aka` store this plugin
|
|
776
|
+
writes. The plugin works completely on its own; this is additive (and the path to
|
|
777
|
+
future multi-agent support). Ask — per the execution contract's decision rules:
|
|
778
|
+
|
|
779
|
+
**Want the AKA CLI + dashboard too?** — "The `aka` CLI adds a local user
|
|
780
|
+
interface + terminal dashboard and on-demand scans."
|
|
781
|
+
|
|
782
|
+
1. **Yes, add it** _(recommended)_ — "adds the `aka` command: stats, a terminal
|
|
783
|
+
dashboard, a local user interface, and on-demand scans"
|
|
784
|
+
2. **Not now** — "skip — you can add it anytime with the one-liner below"
|
|
785
|
+
|
|
786
|
+
**Yes, add it** is the install authorization — run the bootstrap installer
|
|
787
|
+
directly, with no second question (it downloads the self-contained `aka` binary for
|
|
788
|
+
their platform — no Node.js or npm required — and links it onto PATH). Run the
|
|
789
|
+
line for their OS:
|
|
790
|
+
|
|
791
|
+
```bash
|
|
792
|
+
# macOS / Linux
|
|
793
|
+
curl -fsSL https://raw.githubusercontent.com/akasecurity/ai-tc/bin-latest/tools/installer/install.sh | sh
|
|
794
|
+
|
|
795
|
+
# Windows (PowerShell)
|
|
796
|
+
irm https://raw.githubusercontent.com/akasecurity/ai-tc/bin-latest/tools/installer/install.ps1 | iex
|
|
797
|
+
```
|
|
798
|
+
|
|
799
|
+
The one-liner pins to the latest published binary release **tag** (`bin-latest`),
|
|
800
|
+
never `main` — each binary release (`bin-v*`) moves that tag to its commit, and
|
|
801
|
+
the installer verifies the downloaded binary against the release's `SHA256SUMS`
|
|
802
|
+
(fail-closed), so a corrupted or tampered download is refused. To pin an exact
|
|
803
|
+
version instead, set `AKA_INSTALL_REF=bin-v<version>` before running the line. If
|
|
804
|
+
no `bin-v*` release exists yet the one-liner fails closed rather than guessing.
|
|
805
|
+
|
|
806
|
+
After it completes, point them at `aka init` then `aka dashboard`. If they chose
|
|
807
|
+
**Not now**, show the one-liner once so they can add it later, and move on —
|
|
808
|
+
declining keeps the plugin fully functional standalone.
|
|
809
|
+
|
|
810
|
+
**Fail open.** This install is optional, so it must never derail the session. If
|
|
811
|
+
the installer fails for any reason — Node missing, network/registry error, a
|
|
812
|
+
non-zero exit, or the checksum check rejecting a bad download — briefly report
|
|
813
|
+
what happened, show the one-liner so they can retry later, and continue the
|
|
814
|
+
wizard normally. The plugin is already fully set up and works on its own; a
|
|
815
|
+
failed CLI install changes nothing about that.
|
|
816
|
+
|
|
817
|
+
**Close the wizard.** The first-run summary already confirmed the saved posture
|
|
818
|
+
and pointed at the aka-health skill. Whichever way the CLI offer went —
|
|
819
|
+
installed, declined, or a failed install you already reported — end with one
|
|
820
|
+
warm close: "That's it — I'm watching out for Antigravity going forward."
|
|
821
|
+
|
|
822
|
+
Before you finish, confirm every AKA_SHOW region on the path you took was
|
|
823
|
+
relayed to the user. If you summarized one instead of pasting it, paste it now.
|
|
824
|
+
|
|
825
|
+
## Known limitations
|
|
826
|
+
|
|
827
|
+
Antigravity's hook contract is narrower than Claude Code's in several ways that
|
|
828
|
+
change what AKA can actually do. Be honest about every one of these if the user
|
|
829
|
+
asks why something wasn't caught — never imply coverage this plugin does not
|
|
830
|
+
have.
|
|
831
|
+
|
|
832
|
+
**The IDE does not run plugin hooks.** Skills and rules from a plugin load in
|
|
833
|
+
the Antigravity IDE and show under Customizations, but the `hooks.json` entries
|
|
834
|
+
appear never to fire there; hooks execute in the `agy` CLI. Google has not
|
|
835
|
+
documented this either way, so treat it as observed behaviour rather than a
|
|
836
|
+
guarantee. The practical consequence is the important part: **AKA's live
|
|
837
|
+
detection and blocking only apply to CLI sessions.** Work done in the IDE is not
|
|
838
|
+
scanned as it happens. The AKA skills still work in the IDE (they read the same
|
|
839
|
+
local store), and the worktree scan (`aka scan`) and the dashboard cover IDE
|
|
840
|
+
work after the fact.
|
|
841
|
+
|
|
842
|
+
**Prompts cannot be blocked or redacted.** Antigravity has no `UserPromptSubmit`
|
|
843
|
+
equivalent, and its `PreInvocation` event — the one that fires before the model
|
|
844
|
+
is called — carries no prompt text. No event on this host hands a hook the
|
|
845
|
+
user's message before the model sees it, so a secret pasted into a prompt
|
|
846
|
+
reaches the model. AKA records it (so it appears in findings and the dashboard)
|
|
847
|
+
but cannot stop it. This is the single biggest difference from the Claude Code
|
|
848
|
+
plugin, where a flagged prompt is blocked outright.
|
|
849
|
+
|
|
850
|
+
**A redact policy blocks instead of masking.** Claude Code's PreToolUse can hand
|
|
851
|
+
back rewritten tool arguments; Antigravity's cannot — its output is
|
|
852
|
+
`{ decision, reason, permissionOverrides }` with no field for modified args. So
|
|
853
|
+
when a policy says "redact", AKA denies the tool call and explains what to
|
|
854
|
+
remove, rather than masking the value and letting the call run. This applies to
|
|
855
|
+
file writes too, not just shell commands.
|
|
856
|
+
|
|
857
|
+
**A warn is recorded but not shown inline.** PreToolUse's output has no
|
|
858
|
+
message channel (its `reason` accompanies a deny), so a `warn` policy captures
|
|
859
|
+
and ledgers the finding without printing anything in the session. Point the user
|
|
860
|
+
at the aka-findings skill or the dashboard to see warns.
|
|
861
|
+
|
|
862
|
+
**Tool results are not scanned live.** Antigravity's PostToolUse payload does
|
|
863
|
+
not include the tool's output at all — it carries the tool call again plus a
|
|
864
|
+
step index and an optional error. There is no way for a hook to read, rewrite,
|
|
865
|
+
or withhold a tool result on this host. Secrets that appear in command output
|
|
866
|
+
are therefore caught after the fact, not before the model sees them.
|
|
867
|
+
|
|
868
|
+
**History is scanned; token usage is not.** Because of the two gaps above, the
|
|
869
|
+
only place prompts and tool results exist for AKA to read is the session
|
|
870
|
+
transcript — and the historical scan reads Antigravity's real record shape, so
|
|
871
|
+
secrets in past prompts and model messages **are** found by this wizard's
|
|
872
|
+
calibration and by the backfill. Three things in that same file are still not
|
|
873
|
+
read, and each under-reports rather than mis-reports:
|
|
874
|
+
|
|
875
|
+
- **Token usage and cost produce nothing.** The transcript carries no token,
|
|
876
|
+
model or cost field at any depth, so the reconcile worker recognizes nothing
|
|
877
|
+
and usage reporting stays empty for Antigravity sessions. Do not tell the user
|
|
878
|
+
their token spend is being tracked here.
|
|
879
|
+
- **Tool-call arguments are not scan input.** A secret sitting in a
|
|
880
|
+
`run_command` command line or a `write_to_file` body is not found by the
|
|
881
|
+
_historical_ scan. The live PreToolUse hook does scan those, so this gap is
|
|
882
|
+
about past sessions, not current ones.
|
|
883
|
+
- **The truncated transcript copy is skipped.** Each conversation stores a
|
|
884
|
+
complete file and a truncated one; AKA reads the complete file, so nothing is
|
|
885
|
+
double-counted. A conversation that has only the truncated copy is still
|
|
886
|
+
scanned, but its longer records were already capped on disk and whatever was
|
|
887
|
+
cut is not recoverable.
|
|
888
|
+
|
|
889
|
+
Live prompt capture remains impossible for the reason given above — no event on
|
|
890
|
+
this host hands a hook the prompt text — so what the historical scan finds is
|
|
891
|
+
what had already been written to disk.
|
|
892
|
+
|
|
893
|
+
**`multi_replace_file_content` is not scanned.** Its arguments nest the edits in
|
|
894
|
+
a container whose shape is not documented, so AKA does not guess at it. Single
|
|
895
|
+
-edit writes (`write_to_file`, `replace_file_content`) and shell commands
|
|
896
|
+
(`run_command`) are scanned.
|
|
897
|
+
|
|
898
|
+
**A hook that gets stuck denies the tool call, and it will not look like AKA.**
|
|
899
|
+
This host treats a hook that prints nothing as a `deny`, so AKA's hooks always
|
|
900
|
+
print an explicit allow — on a crash, on bad input, and on their own 8-second
|
|
901
|
+
watchdog. That watchdog is a timer, so it cannot interrupt work that blocks the
|
|
902
|
+
thread: if the local store is heavily contended (several AKA processes writing
|
|
903
|
+
at once), a hook can be killed by Antigravity's own 10-second timeout before it
|
|
904
|
+
prints anything, and the user sees "Tool call denied by <hook>". If a user
|
|
905
|
+
reports a denial with no AKA reason attached, that is the likely cause — it is
|
|
906
|
+
not a policy decision and there is nothing wrong with their command. Retrying
|
|
907
|
+
usually succeeds, since the contention that caused it is transient. Do not
|
|
908
|
+
describe AKA's fail-open guarantee to a user as absolute; it covers every hook
|
|
909
|
+
that gets a turn on the event loop, which is everything except a thread that is
|
|
910
|
+
already blocked.
|
|
911
|
+
|
|
912
|
+
**If the plugin's hooks do not seem to fire at all**, the likely cause is the
|
|
913
|
+
`${PLUGIN_ROOT}` variable in `hooks.json`. It is not documented for Antigravity,
|
|
914
|
+
so each command falls back to the default CLI install location
|
|
915
|
+
(`~/.gemini/config/plugins/aka-antigravity`). If the plugin was
|
|
916
|
+
installed somewhere else, edit `hooks.json` and replace `${PLUGIN_ROOT:-…}` with
|
|
917
|
+
the absolute path to the plugin directory.
|
|
918
|
+
|
|
919
|
+
**The reversible secret vault is not wired for Antigravity sessions**, so this
|
|
920
|
+
wizard does not offer the vault-consent step: everything AKA redacts here is
|
|
921
|
+
one-way (the safe direction), and nothing this plugin captures is ever vaulted —
|
|
922
|
+
even when vault consent was granted through the Claude Code wizard on the same
|
|
923
|
+
machine. Vault pointers minted elsewhere render as literal `[[aka:...]]` tokens
|
|
924
|
+
in Antigravity output (there is no display-side hook to badge them), and a
|
|
925
|
+
pointer inside a shell command is denied rather than executed or substituted.
|
|
926
|
+
If the user asks about recovering a redacted value, point them at the vault
|
|
927
|
+
surfaces that do exist on this machine (`aka vault show`, the dashboard's
|
|
928
|
+
Vault page) rather than implying this plugin can reveal anything.
|