Hook Configuration

Hook behavior is controlled by .crosslink/hook-config.json. This file is created by crosslink init and can be edited to customize enforcement.

Configuration File

{
  "tracking_mode": "strict",
  "intervention_tracking": true,
  "cpitd_auto_install": true,
  "comment_discipline": "encouraged",
  "kickoff_verification": "local",
  "signing_enforcement": "audit",
  "auto_steal_stale_locks": false,
  "reminder_drift_threshold": 5,
  "blocked_git_commands": [
    "git push", "git commit", "git merge", "git rebase",
    "git cherry-pick", "git tag", "git stash", "git checkout -b",
    "git switch -c", "git branch -d", "git branch -D",
    "git reset", "git revert", "git am", "git format-patch"
  ],
  "gated_git_commands": ["git commit"],
  "allowed_bash_prefixes": [
    "crosslink ",
    "git status", "git diff", "git log", "git branch", "git show",
    "cargo test", "cargo build", "cargo check", "cargo clippy",
    "cargo fmt", "cargo run",
    "npm test", "npm run", "npx ",
    "tsc", "node ", "python ",
    "cp ", "mkdir ", "gh ", "cd ",
    "ls", "dir", "pwd", "echo"
  ]
}

Fields

`tracking_mode`

Controls how aggressively crosslink enforces issue creation before code changes. See Tracking Modes for details.

Value	Behavior
`"strict"`	Blocks code changes without an active issue
`"normal"`	Reminds but allows proceeding
`"relaxed"`	No enforcement, only git mutation blocks

`intervention_tracking`

When true, hooks log driver interventions (tool rejections, redirects, etc.) for audit and agent improvement. Default: true.

`cpitd_auto_install`

When true, crosslink automatically installs the cpitd code clone detection tool if not present. Default: true.

`comment_discipline`

Controls how aggressively hooks enforce typed comments on issues. Values: "required" (blocks close without comments), "encouraged" (reminds), "off". Default: "encouraged".

`kickoff_verification`

Default verification level for kickoff agents. Values: "local", "ci", "thorough". Default: "local".

`signing_enforcement`

Controls SSH signature verification strictness. Values: "enforce" (reject unsigned), "audit" (warn on unsigned), "off". Default: "audit".

`auto_steal_stale_locks`

When true, agents automatically steal locks from agents with stale heartbeats. Default: false.

`reminder_drift_threshold`

Number of drift events before hooks escalate reminder frequency. Default: 5.

`gated_git_commands`

Git commands that require an active crosslink issue before execution. Unlike blocked_git_commands, these are allowed when the agent has an active work item. Default: ["git commit"].

`blocked_git_commands`

Git commands that are always blocked, regardless of tracking mode. These are mutation commands that should only be run by a human.

The hook checks if the bash command starts with any of these prefixes. To allow a blocked command, remove it from the list.

`allowed_bash_prefixes`

Bash commands that bypass the issue-required check. These are typically read-only or infrastructure commands that don’t require issue tracking.

The hook splits chained commands (using &&, ;, |) and checks that every component matches an allowed prefix. A command like crosslink list && rm -rf / would be blocked because rm -rf / doesn’t match any allowed prefix.

How the Hook Processes Commands

Git mutation check — If command matches any blocked_git_commands prefix, block it (all modes)
Allowed prefix check — If command matches allowed_bash_prefixes, allow it (all modes)
Tracking mode check — Apply mode-specific behavior:
- Strict: block if no active issue
- Normal: warn if no active issue
- Relaxed: allow

Customizing for Your Stack

Add your project’s build and test commands to allowed_bash_prefixes:

{
  "allowed_bash_prefixes": [
    "crosslink ",
    "make ", "cmake ",
    "go test", "go build", "go vet",
    "dotnet test", "dotnet build",
    "mvn ", "gradle ",
    "docker ", "docker-compose "
  ]
}

Resetting to Defaults

crosslink init --force

This resets hook-config.json and all rules to their default values.