Interlinked Setup

A missing or broken hook binary degrades reads and fails closed on writes (2026-08-31)

The installed hook command accepts its baked binary only when it is a regular, non-empty file. When it is gone, empty, or fails to return an intentional allow/block status (unbuilt clone, moved checkout, interrupted build, corrupt JavaScript), its self-contained wrapper still parses the provider's native tool identity. Claude/Codex reserved read builtins and Cursor's dedicated beforeReadFile event proceed with exit 0 and a degraded warning. Ambiguous generic names on Copilot, Gemini, Cursor preToolUse, and MCP/custom events do not earn that exception. Mutating tools and unknown future tool names receive the provider's native deny response (not a fictional uniform exit-code contract), with the repair instruction on stderr. A shell command is never inferred read-only from command text, even when it looks like cat or git status; only the exact operator commands below escape. Claude's native WorktreeCreate also stays fail-closed. Non-gating events normalize runtime failures to exit 1 (a logged failure that does not claim a block).

The standalone generated runtime has the same terminal boundary for the supported pair. Once a parseable Claude/Codex PreToolUse or PermissionRequest payload identifies the native event, an unexpected top-level exception emits that event's exact deny envelope; a non-gating exception emits no stdout and exits 1. Provider stdout is staged until the surrounding audit work succeeds, so a late exception discards the staged object before the terminal response and can never produce partial or duplicate JSON. The installed foreground wrapper remains the outer fail-closed boundary for experimental providers. Empty or malformed stdin cannot identify a native event and is treated as an invalid hook invocation rather than guessed into a provider decision.

The foreground fail-closed wrapper keeps exact operator recovery commands executable before it invokes even a present runtime: bounded harness start / restart, harness status [--json], read-only doctor [--json], non-destructive disable, and interlinked install-hooks --refresh --preserve-mode. Exact node dist/index.js and npx tsx src/index.ts forms are recognized too; an arbitrary absolute */dist/index.js is not. The two source-build spellings (npm run build and node scripts/build-atomic-cli.mjs) are a checkout-local exception only: the current directory must be the same checkout that owns the baked dist/hook-entry.js path, its package must be named interlinked-cli, and it must carry the canonical build declaration and script file. An application repo does not bypass its installed hook merely because it happens to use either build spelling. This prevents a missing or stale runtime from locking out its own diagnosis and repair. It is deliberately not a general shell allowlist: prefixes, suffixes, extra flags outside the bounded command grammar, pipes, and compound commands still run the normal hook and remain blocked. A matching string in a non-shell payload also runs the normal hook; warn-open events never get this escape. If neither the installed command nor a built checkout is available, reinstall or rebuild first, then run the preserve-mode refresh.

Claude PreToolUse and PermissionRequest are supported. On PermissionRequest, Interlinked emits deterministic denies with Claude's dedicated hookSpecificOutput.decision = { behavior: "deny", message } object; that is distinct from PreToolUse's permissionDecision. Allow/ask abstain on stdout so Claude's configured policy and native user prompt retain authority. Non-blocking PermissionRequest diagnostics stay on stderr because that event does not accept generic additionalContext. Codex follows the same abstain-on-allow/ask rule through its provider-specific PermissionRequest response path.

Codex additionalContextLimit applies only to SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, and SubagentStart. Permission decisions, Stop/SubagentStop continuation reasons and compaction diagnostics use separate output channels. Installing limits on those events causes Codex configuration warnings. Both install paths omit them; reinstalling also removes obsolete limits from Interlinked-owned handlers while preserving foreign hooks. Use the manifest-scoped refresh below for an existing adapter install. Changed project hook definitions may need renewed review in Codex /hooks. Stop/SubagentStop continuation is emitted only for an explicit harness block. Allowed or approval-requested diagnostics stay on exit-0 stderr without restarting the agent; Stop has no approval channel. Updating this translation requires the compiled hook runtime to be rebuilt or upgraded, not a hook-matcher change.

Claude's installed WorktreeCreate hook is a deliberate hard stop: that native event replaces Claude's default Git behavior, and Interlinked fails it without returning a path. Across every client, the shared shell guard also blocks git worktree add; list, remove, and prune remain available. Interlinked uses a ban rather than a race-prone concurrent-count cap.

Stale installed hooks (the pre-2026-08-28 SILENT fallback, a deregistered event entry, an old binary path) are repaired with interlinked install-hooks --refresh --preserve-mode — the hooks-only path (added 2026-08-29, hardened 2026-08-30). It re-renders ONLY the Interlinked-owned entries already in installer-manifest.json at their recorded scopes. A Codex install made before the 12-event Interrupt catalog also needs this refresh, followed by review in Codex /hooks: adding the event changes the definition hash and therefore trust state. A corrupt manifest refuses with the bytes preserved (strict per-row validation). Restore a trusted backup or repair it to the valid schema; do not delete it and then run refresh, because the missing ownership record also refuses and cannot identify which hooks are Interlinked-owned. Every file the run can touch — project AND $HOME-scope settings, Codex's config.toml, the manifest — is snapshotted (bytes + file mode) first; any install failure, any skipped target, or any failed final-state verification restores the whole snapshot and fails. That rollback covers HANDLED failures only — an OS crash mid-write cannot run the in-memory restore. Verification is STRUCTURAL (shared with the doctor install drift check): each expected hook entry exactly once at its native JSON path, any Interlinked-owned command outside the adapter's current render fails (the canonical ownership recognizer, so old binaries and legacy .mjs installs are caught whatever their quoting), and Codex's [features] hooks = true via the table-aware reader — duplicate [features] tables or duplicate assignments fail. The manifest itself is strictly validated: unknown runners, invalid scopes, prototype-chain path segments, duplicate runner rows, and any settings path that does not match the adapter's own derivation all read as CORRUPT, and install/uninstall/refresh refuse rather than overwrite the evidence. Uninstall removes hooks by owned-entry recognition, never by stored array index — a user hook added after install is safe wherever it sits. Ownership is shell-position parsed. An adapter entry needs the exact hook-entry.js / interlinked-hook basename, a registered --runner, and a present --event; legacy .mjs ownership needs the reserved .interlinked/hooks/interlinked-activity.mjs path or its exact generated assignment form. A command that only prints, comments on, looks like, or invokes a user script with the same basename without those required shapes is not claimed. Project attribution reads the invoked script path, not text elsewhere in the command. It NEVER writes enforcement mode, cloud config, or guard rules. Do NOT repair with a plain interlinked enable or a plain install-hooks — both also select and write an enforcement mode (the --mode default is "balanced"). --dry-run previews; a second run reports unchanged.

A normal install replaces ownership only after the adapter finishes its semantic post-install step. A selected runner that is skipped (for example, malformed project settings) cannot purge a working hook at another scope. If a replacement's post-install step fails, its attempted settings file is restored and the prior one-row manifest entry remains authoritative; a first-time failure has no prior state to restore, so its partial hook and failed manifest row remain together for uninstall-hooks to remove. In either case the command reports failure rather than claiming the runner is ready.

Diagnosing problems

Project E2E interlinked tests e2e doctor retains report version 1 and adds optional evaluation: "not-evaluated" and prerequisites fields to dependent checks. A ledger failure leaves receipt validation unevaluated; unresolved contract references prevent complete acceptance/toolchain success. Known missing preparation tools can still fail independently. POSIX command inspection checks regular executable files under the runner's PATH/cwd. A same-suite artifact expected after preparation is a warning, not verified availability; preparation commands never receive that exemption. Runtime placeholders or unsupported platform lookup stay unverified. The doctor does not execute preparation.

Hook capability inventory and experimental clients

interlinked harness capabilities --json includes the sourced ecosystem catalog, adapter event/control declarations, installer manifest, last provider emission and filesystem coverage state. selected describes the adapter's subscription policy; inspect the manifest to establish installation. An emitted response or matching definition hash does not certify that the provider enforced it. Native enforcement remains unmeasured until a provider/version/mode conformance run establishes it.

Factory Droid (factory-droid), Windsurf (windsurf), Google Antigravity (antigravity) and Crush (crush) are explicit experimental adapters through interlinked install-hooks --runner <id>. They require a built hook-entry runtime. They are separate from the seven enable --clients integrations and do not expand skill installation targets. Their command wrappers currently target POSIX shells; Windows shell behavior and native headless behavior are not certified. Antigravity uses .agents/hooks.json, separate from Gemini CLI's .gemini/settings.json.

Claude FileChanged installs without a static matcher. SessionStart, CwdChanged and FileChanged responses publish the complete current watchPaths list. FileChanged is an observation after a write; it cannot deny or undo that write. PostToolBatch can cancel the loop before the next model request. Codex does not acquire either native event merely because it uses Claude-shaped payloads; daemon filesystem observation supplies a separate local fallback. Expanded boundary handling requires the compiled runtime. The adapter installer refuses a generated compatibility script instead of registering events that it cannot serve. Build the checkout and refresh hooks; previously installed legacy scripts retain their older compatibility behavior.

The public interlinked-cli/hook-bridge export provides an application-owned Think tool bridge and a Durable Object storage journal adapter. It is not installed with coding-client command hooks. See the repository's docs/hook-normalization.md for its admission, replay and deployment contract.

interlinked doctor is the first stop. It runs local + system + server checks and exits non-zero if any check fails. --fix repairs common drift (regenerates a drifted hook script, safely refreshes Interlinked-owned skill copies, strips malformed permission rules, migrates legacy config).

interlinked doctor            # diagnose
interlinked doctor --fix      # auto-repair what it safely can
interlinked context --json    # show the effective merged config
interlinked env               # list supported env vars + current values

What doctor's client rows do and do not prove (2026-08-30). Doctor checks the hook-config location for every client in the settings registry — Claude Code, Codex, Copilot, Gemini, Cursor, OpenCode, and Pi — reading each path from that one registry instead of restating it (the hardcoded copy it replaced pointed Codex at .codex/config.toml, which holds only the feature flag, so doctor warned that every CORRECT Codex install was missing its hooks). Consequences worth knowing:

• Codex gets three rows, deliberately. The hooks row reads .codex/hooks.json; a second row reads the [features] hooks = true gate in config.toml, table-aware — a hooks = true under some other table does not count. Installed hooks with the flag off are reported as INERT, not missing, because those are different repairs. The third row checks .interlinked/hook-runtime.json: it passes only after Codex executes the current hooks.json definition hash. If it warns, open /hooks, review the definition, and run a hooked action.
• The flag writer canonicalizes to a single hooks key. Whatever mix of hooks / codex_hooks, true / false, duplicated or commented, [features] already holds, the writer leaves a single hooks = true — comments, unrelated tables and the file's line endings intact. Duplicate TOML keys are a parse error, so the old "add a canonical key beside what we found" behavior could report a successful migration for a config Codex then refused.
• A failed post-install now fails the install. Codex is the one runner whose hooks.json is inert without a second write, so when that write throws, install-hooks reports ok: false, lists the runner under post_install_failures, marks the manifest entry post_install: "failed", exits non-zero, and enable reports the client as not installed. It used to log one stderr line and report success.
• A passing hooks row means the config is present, not that execution is verified. The Codex execution row is the stronger live proof for the current definition. Codex installs all twelve native events from the shared capability catalog. Copilot and Gemini adapter normalization and the Cursor duplicate-invocation question are open work; treat those three runners as unproven. OpenCode/Pi have managed-bridge execution tests, but their narrower native APIs still make them experimental rather than Claude/Codex-equivalent.

Likewise enable --dry-run's per-client event counts are computed from the adapter that performs the install (they were prose literals that had drifted, so the preview promised numbers the install did not deliver). They count REGISTRATIONS, not verified provider capabilities.

What "healthy" looks like in doctor: config dir + both config files present, hook script present, per-client "Hooks installed", and Harness server: Running (PID …) -- socket answering. A zombie is a fail here, never a pass. Hook detection shares one ownership predicate with the installers, so an adapter (hook-entry.js) install is recognised as installed rather than reported missing. A manifest-tracked hook binary that no longer exists is a fail, even when the settings document still has the expected entries. A missing token on a non-localhost server is a fail; on localhost it is only a warn (dev mode allows unauthenticated).

When the daemon will not stay up

A daemon that fails before binding its socket exits 78 (EX_CONFIG) and appends an exit row with reason: "startup-failed" to .interlinked/daemon-events.jsonl. It no longer lingers as a zombie. Read that ledger before theorising — it separates a failed bind (78) from a graceful stop, a lost ownership race (0, orderly, not a failure), and a crash.

tail -n 20 .interlinked/daemon-events.jsonl   # why did it leave?
interlinked harness reap                       # list orphan daemons (--force kills)
interlinked harness restart                    # the usual fix

Bind attempts are bounded with backoff, and a socket that answers is never unlinked — a live incumbent wins and the newcomer exits instead of stomping it. Only a silent, stale socket file is cleared and retried.

Dev loop after editing the CLI source: interlinked reload rebuilds the CLI in its own checkout, refreshes this repo's hooks and deployed skills, and restarts the daemon only if something the daemon executes changed.

The package build is runtime-preserving, not a whole-directory transaction. One repository-scoped lease prevents concurrent compiler runs; an equivalent waiter coalesces after the owner finishes. The owner bundles, repairs declarations, copies assets, and checks every shipped entry in a sibling staging directory, then refuses publication if a product build input changed meanwhile. Publishing atomically renames shared chunks/assets first and runtime entrypoints last (hook-entry.js last of those and therefore the handled-failure runtime commit point). The entry phase snapshots existing entries and rolls back anything already replaced if a later entry fails. This is not crash-atomic across several entry renames; after process/OS loss, each old-or-new entry remains independently runnable because both generations' hashed chunks stay present, and the next build converges the entries. dist/ itself is never removed, and prior hashed chunks remain available to a running daemon's later lazy imports. A fault during shared-file publication can therefore leave harmless new immutable files in dist/, but it leaves the previous entry generation in place. Fix the reported error and retry instead of reconstructing dist/ by hand.

Config & environment

• .interlinked/config.json (committed): server_url, default_project, mode (operational tier), skip_paths, pii_patterns, nested harness feature flags.
• .interlinked/config.local.json (gitignored): access_token, agent_name, workspace_id, sync_mode, active_server + servers map, guard_mode, data_dir.
• .interlinked/semantic.json (committed): optional semantic-index enablement, exact pinned model reference, and source/test include policy.
• .interlinked/semantic.local.json (gitignored): local-only CPU/runtime topology. Remote URLs, API tokens, and cloud fallbacks are rejected by the v1 schema.
• Env overrides (win over both files): INTERLINKED_SERVER_URL, INTERLINKED_ACCESS_TOKEN (alias INTERLINKED_TOKEN), INTERLINKED_AGENT_NAME, INTERLINKED_WORKSPACE_ID, INTERLINKED_SYNC_MODE, INTERLINKED_HOME (relocates the whole config dir), INTERLINKED_DATA_DIR, INTERLINKED_CLIENTS (non-interactive bootstrap only).

enable, adopt, doctor, metrics, hooks, and search do not auto-download embedding weights. The experimental semantic commands also require compatible local llama-embedding and llama-tokenize executables (override their command names only in semantic.local.json). Model weights live in the platform user cache; project vectors live under the gitignored .interlinked/index/functions/ directory and are never synced.

Two different mode commands — do not conflate them:

• interlinked mode <balanced|strict|lenient> → per-check policy preset → check-policy.json, PLUS the preset's guard posture (TDD/test-first tier, per-edit coverage + debt mode, session-end nudges, commit cadence) into guard-rules.json. Since 2026-08-30 the loader actually honors that posture: the team tier merges the whitelisted safe fields (booleans + the three posture enums) and drops runtime knobs like budget_ms. --local writes BOTH halves to the personal tier (check-policy.local.json + guard-rules.local.json) — a personal mode switch never edits committed team policy. The wizard's scope (diff_aware.enabled) and dead-code writes load through the same whitelist. The mode switch is transactional in BOTH directions (a refused guard merge writes neither file; a failed check-policy write rolls the guard file back), and the three posture enums are value-validated at the final loader boundary for BOTH tiers — an invalid value is dropped (built-in default applies) and interlinked doctor names the file, field, and value.
• interlinked harness mode <budget|quality|ci> → operational timeout tier → config.json mode + regenerates the hook. Requires harness restart to take effect.

Auth & server (optional)

interlinked login --server https://your-server.dev   # OAuth PKCE (opens browser)
interlinked login --token "$INTERLINKED_TOKEN"        # CI / headless
interlinked attach --agent my-bot --auto              # link identity + workspace
interlinked logout [--all]

• localhost/127.0.0.1 = dev mode → auth skipped (setup/init skip login for local servers).
• Token resolution: CLI token in config.local.json → auto-refresh → Claude Code credential fallback (~/.claude/.credentials.json).
• Sync modes: realtime (default; per-event post + session-end batch), manual (per-event only), local (no server posts at all).

Turning it off

A valid stand-down marker suppresses hook self-heal. If disable reports the old daemon is still running, run interlinked harness stop: that already-running process may continue to evaluate calls until it exits, but hooks will not resurrect it afterward.

Gotchas

• disable is non-destructive by default now — bare disable just stands down; use --uninstall (or reset --force) for real teardown.
• clean defaults to dry-run; reset requires --force.
• Install paths have non-interchangeable uninstall semantics. uninstall-hooks only cleans an install-hooks-style install; use disable --uninstall / reset to clean an enable install.
• Claude Code merge-up dedup: enable refuses to install Claude hooks when an ancestor .claude/settings.json already has them (would double-fire) — run enable from that ancestor.
• Daemon discovery stops at a Git boundary. A hook invoked in a linked worktree or submodule uses that worktree's .interlinked/ runtime and never borrows a daemon socket from the parent checkout. Ordinary monorepo subdirectories still discover the nearest ancestor daemon.
• Gemini is a compatibility lane, not the Antigravity adapter. Consumer Gemini CLI service ended in June 2026, while enterprise and paid API-key Gemini CLI use remain supported. The current gemini client installs Gemini CLI hooks/skills; do not treat it as Antigravity.
• OpenCode and Pi installs are managed source bridges. Project scope writes .opencode/plugins/interlinked.ts or .pi/extensions/interlinked.js as an Interlinked-owned whole file; user scope uses ~/.config/opencode/plugins/interlinked.ts and ~/.pi/agent/extensions/interlinked.js. Install refuses to overwrite a foreign file at that path, and uninstall preserves a bridge whose bytes changed after install. A loaded bridge writes its provider row to .interlinked/hook-runtime.json, but only Codex currently has a dedicated doctor trust-verification row. Restart OpenCode after install (its plugin trust is implicit). In Pi, run /reload or restart and approve the project-extension trust prompt.
• Their native parity is intentionally bounded. OpenCode's stable tool-before hook cannot open confirmation, so ask denies; permission bus and session.idle/Stop are observation-only. Pi prompts through ctx.ui.confirm when interactive and denies headless; user_bash gates direct shell commands as well as model tool calls. Neither exposes dedicated native MCP, subagent, or worktree lifecycle hooks. The shared shell rule still blocks git worktree add.
• reload needs a source checkout — it rebuilds the CLI checkout the running binary resolves to (typically a ~/.local/bin symlink), not the current repo.
• --json support is per-command; unknown flags error. doctor takes only --fix/--json.

Related skills

• interlinked-verify — project e2e adoption after enable: interlinked tests e2e discover --out report.json, review, tests e2e adopt --from report.json (advisory unless --mode required), tests e2e doctor. Discovery proposes; it never accepts inferred behavior.
• interlinked-harness — what the guard blocks and how to respond when a tool call is refused.
• interlinked-observability — inspect the activity the hooks capture (status, activity, logs).
• interlinked-coordination — the optional server-backed side (tasks, messages, workspaces).
• interlinked-semantic-index — explicitly install a model and build/query the local function index.