Interlinked Harness

interlinked-harness — the guard: what blocks you & how to respond

Predict changes to guards

The prediction phase includes a local JS/TS if-ownership oracle, independent of Supermodel and graph_prediction.enabled. Its default mode is enforced; harness.guard_prediction.mode in shared .interlinked/config.json accepts enforced, shadow (record/reveal without refusing), or off.

Before intentionally changing which if guards an existing return or throw, declare the expected ownership change. The raw before/after AST comparison runs before content checks; do not brace or format away an unexpected change. Unpredicted changes block as protocol mismatches, not proven bugs. Correct the proposal, or reconcile the exact revealed change with a rationale and behavioral validation. A matching prediction does not prove correctness.

Receipts are JSON at .interlinked/predictions/guards/<sha256(session)>/<id>.json. Fields: version: 1, session, id, file (canonical repository-relative path), beforeSha256, afterSha256, nonce (nonempty declaration identifier), and changes: an array of {owner, statement, before, after}. Statement and condition strings use parser token spellings joined by spaces. Each guard is {condition, branch: "then" | "else"}; arrays list outer to inner guards. The ID is SHA-256 of JSON.stringify([1, file, beforeSha256, afterSha256]), with UTF-8 hashes of the exact source bytes. Use the native session identity printed in a reveal. The reveal includes the measured fields and receipt path. After a reveal, include reconcile: id and a nonempty rationale; a late prediction alone cannot pass. Identical retries retain their declaration; changed bytes, file or session require a matching receipt. Never use a wildcard acknowledgment.

The append-only predictions/guard-events.jsonl retains reveal, predicted, and reconciled evidence; acceptance never erases a surprise. Dry runs do not persist events. Invalid or inaccessible protocol state cannot authorize a changed proposal. This is local intent bookkeeping, not an adversarial security boundary.

The initial oracle handles unique existing statements in identifiable function scopes, plus unchanged complete function bodies. Changed ambiguous/anonymous scopes and changed statement text produce partial/NOT CHECKED evidence. It does not establish loop/switch/exception dominance, semantic predicate equivalence, deleted statements, cross-file moves, or arbitrary shell effects. Native cold fallback runs the same oracle; a standalone generated hook without the daemon reports NOT CHECKED because it has no AST runtime. Restore the daemon or use interlinked-hook for that check. Single-line guards remain valid code; brace style is a separate policy.

Claude's demonstrated native PostToolBatch boundary coalesces TypeScript checks for declared single-file edits. The final tree is checked before the next model request; security guards and hard complexity caps remain per edit. Final compiler findings are repair context, with unresolved work enforced at Stop/commit. See interlinked-verify for fallback and recovery behavior. Merely using multiple Edit calls is not evidence of a retry: correlate their emission time and assistant message with hook feedback.

Repeated pre-edit content advice, test-evidence limitations, and unchanged coverage gaps are deduplicated for model delivery. Full observations remain in local evidence. Changing coverage counts alone do not repeat the same instruction; a recovered gap that recurs or a different unavailable-check reason is announced again.

Claude and Codex Stop/SubagentStop advisories remain operator diagnostics on stderr. Only explicit blocking repair decisions request another model turn. Source guidance is sent during editing. File-size advice and per-function gates share native edit/patch content projection; unreadable or invalid updates stay unmeasured. Shell effects remain post-execution evidence unless a supported pre-write path is used.

PostToolUse classifies recognized untracked Python environments, installed Node dependency trees and named harness outputs before authored-source checks. Explicit edits, tracked files, protected policy and unsafe/symlink paths do not receive this exemption. Security scope stays separate; excluded files are not passes and runtime-input fingerprints are not narrowed. The same source role separates recovery batches. Repeated unavailable-check diagnostics are deduplicated for delivery; raw findings and unresolved evidence remain. Retry when prerequisites change, not merely because the same diagnostic repeats. Missing evidence cannot yield “all clean.”

For edits outside the guarded repository, both command-based and named external checks (affected tests and dependency audit) skip this repository's runner. Inline content checks remain available. Security findings on excluded dependency files retain normal severity and enforcement; source-quality exclusion is not a security exemption.

The built-in generic rm prior-inspection rule is advisory. A recent literal Read event does not prove inspection of the deletion targets, and clients may expose different read tools. Inspect the intended targets using the available tools; this heuristic does not require a particular invocation. Deterministic destructive-command, reservation and protected-file decisions still apply. Do not infer safe deletion merely from a recent unrelated read.

Guard audit records retain references for repeated warning text. Use interlinked data search --source warning-occurrences to inspect full first/changed messages, hashes and occurrence counts; data show ID opens their raw evidence. This bounds repetition in the activity mirror without changing the guard decision or the warning returned by the evaluator. A later not-reported observation does not prove that the underlying issue was fixed.

Interlinked runs a local daemon that evaluates each pre-execution event the installed runner exposes to its hook surface (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

For the experimental Cowork plugin, first load interlinked-cowork. Its portable guard is a subset of this daemon: exact tool/path denials and the shared destructive command guard. Native crashes/timeouts were observed to fail open; the plugin's launcher mitigates child failure but cannot enforce an absent/provider-killed hook. Host file policies require explicit bridge mapping and matching file snapshots.

• 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

• Each installed hook event ships its payload to the daemon over a Unix socket. The daemon runs an ordered set of phases; the first phase that returns a terminal decision wins.
• Framed daemon RPC validates each method's request shape, including nested hook metadata and administrative arguments, before dispatch. The client accepts only matching-id responses with the expected method result shape. Malformed frames do not become successful decisions; the existing timeout and fallback behavior still applies.
• Local quality-check overrides validate each supplied field before merging it. Malformed fields are ignored while valid fields and sibling checks survive; new checks require the complete mandatory configuration. Team overrides affect existing checks only. Default configuration copies preserve non-JSON values such as an unlimited (Infinity) step limit.
• Content-scanner allowlists skip malformed entries. Known entry kinds require their declared string fields; an unrecognized scanner runtime cannot select a backend. These checks apply to these boundaries and do not imply that every legacy configuration section has a schema.
• Decisions: block (tool refused, you see the reason), ask (human confirmation — Claude and supported Cursor gates can ask natively; interactive Pi calls ctx.ui.confirm; headless Pi, OpenCode's stable tool gate, Codex PreToolUse, Copilot, and Gemini deny instead; Claude/Codex PermissionRequest allow/ask abstain so the provider retains authority), or allow (may still carry non-blocking warnings, or an updated_input rewrite).
• Built-in rules are regex patterns on the command/tool-input. Use interlinked harness checks for the authoritative current inventory. Patterns are ORed over positive entries; 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.
• Python open(...) checks inspect executable calls and recognize write and append modes; read-only calls and quoted examples do not establish a file write. Keep malformed tool input tests at the raw hook-input boundary rather than passing invalid normalized events.
• The log-output guard measures ordinary single-file head/tail windows of up to 200 lines before rejecting a file over 100 KiB. Small windows pass on large logs; a selected line over the byte budget still blocks. Signed counts and unfamiliar option combinations retain the file-size gate. Daemon and generated-hook paths use the same bounded reader.

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)

When you're BLOCKED: what to do

For selected-hunk staging, prepare and review a patch, then run git apply --cached <patch>. It changes only the index and preserves other working-tree edits. git add -p, -i, and -e remain blocked as interactive operations; use git add <paths> for whole files. Flags on a later shell command do not make staging interactive; a backslash-escaped newline continues the same command and retains its interactive restrictions. A normal git apply or git apply --index still writes the working tree and must use the content gate.

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

2. 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).

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

4. 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.
   • A [interlinked:sequence] pre_block (trajectory detectors such as secret_read_then_network_call) is deferred the same way, but the marker must sit in the call itself — the Bash command text, or the content you are writing — and must name the detector id exactly. The call then runs and the harness logs [interlinked:sequence-deferred] with your reason. These detectors latch on session state, so without the marker one confidential read can block later outbound network calls.

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

Loopback requests after a sensitive read. The sensitivity guard and secret_read_then_network_call share destination-aware classification. Explicit HTTP(S) curl requests to localhost, IPv4 loopback (127.0.0.0/8), or IPv6 loopback (::1) are exempt, including ordinary request/data/header flags. Simple nc/ncat/netcat loopback connections are also exempt. Wget requires --max-redirect=0 and a supported simple invocation. Each network command and destination must qualify: a local request never exempts another remote request in the same shell command. Sensitivity remains unchanged. LAN/private addresses, unknown destinations/options, shell expansions, curl redirect flags, explicit proxies, alternate resolution and config-file options retain guarding. Explicit environment assignments selecting proxies or client configuration also retain guarding. This is a static command classifier; it does not inspect ambient client configuration or prove what a local service does with received data. Other guards continue to apply.

Commit-risk nudge. On a real Bash git commit, [interlinked:jit][heuristic] warns when the currently staged diff ranks at p90 or above against recent commits in this repo. It is advisory, never blocks, and does not replace subsequent commit gates. Inspect it with interlinked metrics jit --staged --message '<planned subject>'; see interlinked-quality-gates for calibration, interpretation and snapshot limits.

An agent must not create a Git worktree to route around shared-workspace policy. Use the current workspace. If isolation is genuinely required, ask a human operator to provision an approved worktree; listing and cleanup of existing worktrees remain allowed.

Warnings: [proven] vs [heuristic]

Filesystem observations and native control limits

The daemon watches protected policy files and literal in-workspace reservation paths, then reconciles content identities periodically and at delivery boundaries. Writes by a shell, editor or agent can create durable pending verification entries. Writer identity is unknown; a reservation is not proof that its holder performed the write. Glob reservations, symbolic links, inaccessible or oversized files remain explicitly unmeasured. A stopped or unavailable observer cannot certify coverage.

harness coverage status --progress --json reads cached observation time, generation and recovery counts without reconciling files or returning receipt history. Use it for progress, not to certify current bytes. Plain harness coverage status --json still reconciles and returns full evidence. Neither status command starts recovery. Receipts with nonempty unavailable retain completed checks as partial evidence while keeping the version pending. Retrying is not made unnecessary merely by having a receipt; safe cross-run reuse needs the relevant check input identities.

harness coverage accept-policy <digest> records an explicitly reviewed current policy identity. It neither runs checks nor restores old policy bytes. A later Claude ConfigChange can refuse application of a differing identity, after the disk write has happened. This is not an immutable trust anchor or a universal policy reload interlock. Do not describe watcher readiness as baseline-integrity enforcement.

Native translations are recorded in .interlinked/hook-translations.jsonl by the compiled entry point. A post-tool refusal may become context, continuation or batch cancellation; observational events cannot enforce a denial. Copilot/Gemini approval requests conservatively deny where native approval is not certified. Experimental Antigravity uses force_ask; Antigravity and Windsurf refuse a required input rewrite that their hook cannot apply. Read translation status separately from native enforcement. Harness-disable trajectory detection reads executable command positions, so a mutation-test filename containing kill is not a process-kill event. Failed commands do not establish a successful disable. A later event served by the daemon retires process/socket-outage suspicion; it does not retire a recorded weakening of disabled_rules. Shadow verdicts remain advisory and do not include a misleading BLOCKED: prefix.

The optional-chain check uses syntax grouping: passing value?.field to a function and then accessing that function's result is different from (value?.field).name. Without optional TypeScript syntax support it cannot establish this finding; silence is not a clean verdict. SQL migration checks likewise cannot prove a column absent from an interpolated column list. For it.each(table)(name, callback), assertion checks inspect the callback, not functions inside the data table. An unparsed callback cannot prove assertion absence; table assertions also cannot satisfy an assertion-free callback.

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 varies by runner. On the supported Claude and Codex gate surfaces, a block reason is surfaced through the provider's blocking channel. Experimental adapters target their native response or exit-code shapes, but registration is not proof that every provider version enforces them identically. Claude and Codex use model-visible additionalContext only on events whose contracts support it. A Claude PermissionRequest deny uses hookSpecificOutput.decision = { behavior: "deny", message }, not PreToolUse's permissionDecision; allow/ask abstain on stdout, and non-blocking PermissionRequest diagnostics stay on stderr. Cursor uses additional_context on generic postToolUse. OpenCode appends post-tool feedback to tool output; Pi appends it to tool_result and can notify an interactive UI. Copilot remains stderr-only and some lifecycle events are observation-only. Allow-warnings are easy to overlook — read them.

Codex Stop and SubagentStop request continuation only for an explicit harness block. Its reason is preserved before any additional context or warnings. An allow or ask decision emits no stdout; diagnostics stay on exit-0 stderr for operator inspection, not model-visible continuation. These events have no native approval channel. Pending hook-coverage evidence alone does not force another turn or become checked by allowing completion; inspect coverage status separately.

Silence = no model-visible finding, NOT "everything was checked" (2026-08-27). A served, clean PostToolUse result writes ZERO BYTES — no [interlinked:Bash] all clean (354ms) row, not even an empty {} envelope — because runners render one hook row per response and parallel tool calls multiplied that into unusable noise. Outage visibility is phase- and runtime-specific:

No output therefore never proves the full daemon check set ran. To distinguish a served clean result from a silent degraded PostToolUse path, ask interlinked harness status or interlinked doctor; inspect .interlinked/activity.jsonl and the statusline for the per-call state.

The block row is load-bearing: the response path decides on the DECISION, never on whether the warning list happens to be non-empty. If you are about to rely on "the harness would have caught it", confirm the daemon is answering first — silence is not evidence that it was.

Test edits use the same hook loop. Deterministic introduced test theatre (assertion-free or tautological cases, SUT self-mocking, focus markers, unconditional skips) blocks before the write. Lower-confidence but low-noise test-quality findings are PreToolUse warnings so even a small writer can correct them immediately; context-heavier suite review stays in PostToolUse. Do not silence a warning merely to land the edit—assert a precise observable behavior, or justify the actual public compatibility contract.

With explicit structural_checks.test_first_mode: "enforce", an empty repository does not exempt new JS/TS or Python source from companion-test requirements. Write the first meaningful test, observe its failure, then implement the behavior. Existing pair-debt workflow remains available after a suite exists; warning mode stays advisory. This creation gate does not itself prove that every later change followed red–green TDD.

Test-discrimination advisories are post warnings and also run under verify --all-checks. They review fallback-only evidence, indistinguishable positive/negative expectations, unpinned spy arguments, wildcard observables, in-tree fixtures, fixed ports, ambiguous throw messages, unguarded catch assertions, vacuous loops, mock return echoes, duplicate bodies, spies without restoration, export existence smoke tests, and commented-out assertions. They never block. Evaluate the intended contract: forwarding a mock value or preserving an export can be legitimate. Fix a detector false positive before rewriting valid tests. spy_without_restore recognizes applicable local cleanup and statically discovered Vitest/Jest restoration settings; clearAllMocks/resetAllMocks are insufficient. Fresh test-owned array literals are exempt, as are fresh test-owned objects; module/suite arrays, shared aliases, and prototype methods still need restoration. Source headers and docs/design/test-discrimination-checks.md describe limits and calibration. A corpus hit count is not precision or proof of a surviving mutant.