@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.
@@ -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.