| name | interlinked-harness |
| description | Understand and respond to the Interlinked PreToolUse guard — the local daemon that BLOCKS dangerous tool calls before they run. Load this when a Bash command or file edit was refused with "BLOCKED: … Suggestion: …", when you see an `[interlinked:<check>]` warning tagged `[proven]` or `[heuristic]`, when a destructive command / force-push / protected-file / secret / repo-confinement rule fired, when a grep was answered by the index, or when you need to know how to legitimately suppress a false positive or disable a guard rule. Covers what blocks, how to read the reason, suppression grammar, determinism tags, and the fail-closed cold fallback. |
interlinked-harness — the guard: what blocks you & how to respond
Interlinked runs a local daemon that evaluates every agent tool call before it runs
(PreToolUse). It is default-permit with targeted forbid: it allows everything except
known-dangerous shapes, which it refuses with an actionable reason and a safer alternative.
It is a fast deterministic guardrail, not a security trust boundary (it's local and
bypassable) — so the right instinct when blocked is to take the suggested safe path, not to
defeat the pattern.
Load this when
- A tool call was refused:
BLOCKED: <reason> / Suggestion: <safer alternative>.
- You see an
[interlinked:<check>] warning (tagged [proven] or [heuristic]).
- A destructive command,
git push --force, protected-file, secret, repo-confinement, or
bash-redirect-bypass rule fired.
- You need to legitimately suppress a check false-positive, or disable a wrong guard rule.
Mental model
- A hook ships each tool call to the daemon over a Unix socket. The daemon runs ~33 ordered
phases; the first phase that returns a terminal decision wins.
- Decisions:
block (tool refused, you see the reason), ask (human confirmation — on
runners without an ask primitive, like Codex/Copilot/Gemini, ask downgrades to deny),
or allow (may still carry non-blocking warnings, or an updated_input rewrite).
- Built-in rules (~119 across ~25 categories) are regex patterns on the command/tool-input.
OR over positive patterns;
negate:true patterns are exceptions. executed_only masks
quoted/heredoc/comment text, so mentioning rm -rf / in an echo is allowed while the
bare command blocks. Compound commands (&&, ||, ;, |, newline) are decomposed and
each part checked.
Two unrelated things are called "guard". This skill is the PreToolUse guard (the
daemon, operated via interlinked harness …). interlinked guard is a separate git
pre-commit/pre-push hook that checks staged files against file reservations — see
interlinked-coordination.
What gets blocked (with concrete examples)
| Category | Blocks (examples) | Allows (examples) |
|---|
| Destructive fs | rm -rf /, rm -rf *, rm node_modules, sudo rm …, dd, mkfs, shred, chmod 777 | rm -rf /tmp/x, rm -rf dist/, rm -rf .wrangler/cache |
| Process killing | pkill node, killall wrangler, kill -9 1234, kill $(pgrep …), … | xargs kill | pkill -f 'wrangler dev', grep -rn "kill -9" src/ |
| Git | git push --force/-f, git reset --hard, git clean -fd, git checkout -- ., git branch -D, git stash drop/clear | git push --force-with-lease |
| DB / cloud / IaC / containers | DROP DATABASE/TRUNCATE/DELETE-without-WHERE, docker … prune/rm -f, kubectl delete, terraform destroy, pulumi destroy | — |
| Info-flow / persistence | env exfil (env | curl …, printenv | nc …), .npmrc/.yarnrc writes, nohup curl … &, crontab -e, systemctl enable, writes to /etc/cron.d/, *.service | — |
| Protected files | Read/Write of *.pem/*.key; Write of *.env* only if secrets detected; Delete of CI configs, migrations/**, .gitignore, lockfiles, Dockerfile | .env.example / .sample |
| Sensitive-file read | Read of .env, credentials.json, service-account*.json, *.pem/*.key | .env.example |
| Repo confinement | any Write/Edit whose real (symlink-resolved) target is outside the repo root | paths under the allowlist / session scratchpad |
| Package installs | any un-allowlisted npm/pip/cargo/go/… install; URL/git/tarball specs — see interlinked-supply-chain | allowlisted + exact-pinned |
| Bash-routed write bypass | a > / tee redirect writing a tracked source file (dodges the content gate) | routed to Write/Edit or interlinked write |
| Content pre_block (introduced-only) | edit that introduces merge-conflict markers, eval(), and other zero-FP checks | pre-existing instances (warn, not block) |
When you're BLOCKED: what to do
- Read the
reason and Suggestion:. The suggestion is the intended path (force-push →
--force-with-lease; rm node_modules → npm cache clean --force && npm install;
pkill node → target the PID or pkill -f 'wrangler dev'). Take it — but the safe flag is
not always the whole answer. For a destructive or history-rewriting op on a shared target
(force-push to main, dropping data), the block is also a prompt to check intent: confirm
the action is warranted and that you have explicit user authorization before proceeding.
- Don't rewrite to dodge the regex. The pattern encodes a real hazard; evading it is the
wrong move (and trajectory detectors watch for evasion).
- Content-check blocks are introduced-only. A
pre_block finding ([check_id] in the
reason) blocks only when your content has more instances of that finding's line text than
the file already had (multiset over whitespace-normalized text — moving a pre-existing
finding doesn't count; a brand-new file counts everything). Fix the line(s) you added,
then retry.
- Legitimate suppression — only when a flagged line is genuinely deliberate:
- Inline, on the line above the finding:
// interlinked-ignore: <check-id> — <why>
(reason separator —, --, or –; comma-separate multiple check ids).
- File/glob-level: an entry in
.interlinked/verify-suppressions.json
({ "<file-or-glob>": { "<check>": {"reason","by","at"} } }).
- Both are honored identically at pre_block, PostToolUse, and
interlinked verify, and are
ratcheted/audited (visible exceptions, not silent bypasses).
- Distinct:
// interlinked: defer <check> -- reason acknowledges a finding without
suppressing it (still logged) — for pre-existing findings you're choosing not to fix now.
- When NOT to suppress:
[proven] findings (tsc/biome/gitleaks/semgrep actually ran) and
any destructive/security guard-rule block. Suppression directives affect checks, not
rules — you cannot // interlinked-ignore a git push --force block. If a rule is
wrong for your repo, the fix is config (below), not a comment. Don't add
@ts-ignore/biome-ignore to silence a [proven] check — that trips suppressions-unjustified.
Warnings: [proven] vs [heuristic]
Every warning is tagged. [proven] = a real compiler/linter/scanner/parser/test-runner
produced it — authoritative, fix it. [heuristic] = regex/AST-shape match that could be a
false positive — evaluate it. No tag = unknown check id (never guessed).
Visibility (Claude Code): a block reason is always surfaced. PreToolUse allow-warnings
are routed through additionalContext (you see them next turn); PostToolUse warnings go to
stderr. Allow-warnings are easy to overlook — read them.
Grep acceleration
The guard intercepts Grep tool calls and Bash rg/grep, queries a trigram index for
candidate files, and can answer the search directly (block-and-answer) faster than a full
scan. It is strictly never-worse-than-native: on small/medium repos it declines and native
rg runs unaccelerated. It's a large-monorepo optimization; you don't manage it. Inspect what
it would match with interlinked index query <pattern>. Your own just-written edits are
immediately searchable (in-memory dirty layer).
Configuring the guard (when a rule is genuinely wrong for the repo)
Config lives in .interlinked/guard-rules.json (team) + .interlinked/guard-rules.local.json
(personal, gitignored). Merge priority: local > team > built-in.
disabled_rules: ["builtin-git-force-push", …] — turn a built-in rule off (built-ins can be
disabled, never edited).extra_exceptions: { "<rule-id>": ["substring", …] } — the rule won't fire if the command
contains a listed substring.- Team/local/distilled files hot-reload within ~2s (
watchFile); interlinked harness restart
forces a full reload.
The cold fallback (dead daemon fails closed)
If a daemon was started for this project but the socket is now unreachable (crashed/hung),
the hook BLOCKS tool calls rather than run unguarded, and tries to self-heal. A subset of
checks still runs inline even when the daemon is down: merge-conflict markers, destructive
commands, package installs, and the per-file line cap. Fix: interlinked harness start / restart, then retry. (If no daemon ever ran here, calls are allowed instead.)
Gotchas
- The "
sleep is blocked" claim in old docs is stale — there is no standalone sleep
block in the current rule set. Don't rely on it.
interlinked harness test "<cmd>" fires a synthetic event at the daemon to see if it
would block — and is itself exempt from destructive rules so you can test them safely. A
chained destructive tail still blocks; "test allowed it" ≠ "the real command is allowed".harness restart clears per-session trajectory state — soft_block "retry allowed" memory
and trajectory detectors reset. A restart mid-task can change guard behavior.[interlinked:trajectory] …(shadow — would block) warnings are advisory only (shadow
mode) — they preview a future gate; treat as signal, not a block.- All five runners get PreToolUse blocking (Claude Code, Codex, Copilot CLI, Gemini,
Cursor). Runners without an
ask primitive (Codex/Copilot/Gemini) collapse ask → deny.
- PII content scanner is separate and opt-in:
interlinked scanner on|off|toggle|status|review.
- Env bypasses (logged, documented-flows only):
INTERLINKED_DISABLE_PACKAGE_GUARD=1,
INTERLINKED_DISABLE_BASELINE_GUARD=1, INTERLINKED_DISABLE_SCRATCH_GUARD=1.
Quick reference
interlinked harness test "git push --force"
interlinked harness checks
interlinked harness status --json
interlinked index query "<pattern>"
interlinked harness restart
Related skills
- interlinked-verify — the check catalog behind the warnings,
interlinked verify, and how to land edits through the gates.
- interlinked-quality-gates — the metric ratchets (line-cap / coverage / complexity) that also block edits.
- interlinked-supply-chain — the package-install gate in detail.
- interlinked-setup — starting/restarting the daemon,
doctor, config.
