Build your first Claude Mod

{
  "name": "block-force-push",
  "version": "0.1.0",
  "description": "A starter mod: refuses a Bash call that force pushes with git, and passes every other tool call through.",
  "author": {
    "name": "Your name"
  }
}

{
  "description": "A tool.call hook that refuses a Bash call which force pushes with git",
  "modules": ["./register.ts"]
}

import type { On } from 'claude-code'

import { isForcePush } from './is-force-push'

/**
 * The mod's one entry. `on` hooks an event with a function `($, e, next)`:
 * `e` is the event's input, `next(e)` runs the hooks beneath, and returning `{ deny }` refuses.
 *
 * @param on the engine's registrar
 */
export function register(on: On) {
  on('tool.call', ($, e, next) => {
    if (e.tool === 'Bash' && isForcePush(e.command)) {
      return { deny: 'Force pushes are blocked by this mod. Ask the person to run it themselves.' }
    }
    return next(e)
  })
}

/**
 * True when a shell command runs `git push` with a force flag (`--force`, `-f`, or `-f` combined with
 * other short flags such as `-fu`) or a forced refspec such as `+main`.
 *
 * It splits on `;`, `&`, `|`, parentheses and newlines, skips leading `NAME=value` words and git's
 * own options (`-C dir`, `-c key=value`), and needs `push` to be the git subcommand, so
 * `cd app && git push -f` and `GIT_SSH_COMMAND=ssh git -C app push -f` are caught and
 * `git branch -f push main` is not.
 *
 * It is a teaching example, not a security boundary: it does not read aliases or scripts, it does not
 * see through wrappers such as `sudo`, `env` or `bash -c`, and it lets `--force-with-lease`,
 * `--delete` and `--mirror` pass.
 */
export function isForcePush(command: string): boolean {
  return command.split(/[;&|()\n]+/).some((segment) => {
    const words = withoutEnvironmentAssignments(segment.trim().split(/\s+/))
    if (words[0] !== 'git') return false
    const subcommandIndex = gitSubcommandIndex(words)
    return words[subcommandIndex] === 'push' && words.slice(subcommandIndex + 1).some(isForceWord)
  })
}

function withoutEnvironmentAssignments(words: readonly string[]): readonly string[] {
  const firstCommandWord = words.findIndex((word) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(word))
  return firstCommandWord === -1 ? [] : words.slice(firstCommandWord)
}

/** Index of git's subcommand: the first word after `git` that is not a global option or an option's value. */
function gitSubcommandIndex(words: readonly string[]): number {
  let index = 1
  while (index < words.length) {
    const word = words[index]
    if (word === '-C' || word === '-c') index += 2
    else if (word.startsWith('-')) index += 1
    else return index
  }
  return -1
}

function isForceWord(word: string): boolean {
  const isForceFlag = word === '--force' || /^-[A-Za-z]*f[A-Za-z]*$/.test(word)
  const isForcedRefspec = word.length > 1 && word.startsWith('+')
  return isForceFlag || isForcedRefspec
}

import { describe, expect, test, tier } from 'claude-code/testing'

tier('user')

describe('register', () => {
  test('refuses a force push', async ($, on) => {
    on('tool.call', () => ({ result: 'ran' }))

    const outcome = await $.tool.call({ tool: 'Bash', command: 'git push --force origin main' })

    expect(outcome).toEqual({ deny: 'Force pushes are blocked by this mod. Ask the person to run it themselves.' })
  })

  test('passes any other call to the hooks beneath', async ($, on) => {
    on('tool.call', () => ({ result: 'ran' }))

    const outcome = await $.tool.call({ tool: 'Bash', command: 'git push origin main' })

    expect(outcome).toEqual({ result: 'ran' })
  })

  test('passes a call to another tool to the hooks beneath', async ($, on) => {
    on('tool.call', () => ({ result: 'ran' }))

    const outcome = await $.tool.call({ tool: 'Read', file_path: '/tmp/notes.txt' })

    expect(outcome).toEqual({ result: 'ran' })
  })
})

import { describe, expect, test, tier } from 'claude-code/testing'

import { isForcePush } from '../hooks/is-force-push'

tier('user')

const cases: readonly (readonly [command: string, expected: boolean])[] = [
  ['git push --force', true],
  ['git push -f origin main', true],
  ['git push -fu origin main', true],
  ['git push -uf origin main', true],
  ['git push origin +main', true],
  ['git -C app push -f', true],
  ['git -c core.editor=vi push -f', true],
  ['GIT_SSH_COMMAND=ssh git push -f', true],
  ['cd app && git push origin main -f', true],
  ['echo hi; git push -f', true],
  ['true || git push -f', true],
  ['echo x | git push -f', true],
  ['sleep 1 & git push -f', true],
  ['(git push -f)', true],
  ['echo hi\ngit push -f', true],
  ['git push origin main', false],
  ['git push -u origin main', false],
  ['git push --force-with-lease', false],
  ['git branch -f push main', false],
  ['git log --grep push -f', false],
  ['echo git push --force', false],
  ['git status', false],
  ['', false],
]

// What the helper does not catch. The starter's guide names these limits, so a test holds them true:
// if a case here starts to be caught, update the guide's wording with it.
const knownLimits: readonly string[] = [
  'sudo git push -f',
  'env git push -f',
  'bash -c "git push -f"',
  'git push --delete origin main',
  'git push --mirror',
]

describe('is-force-push', () => {
  for (const [command, expected] of cases) {
    test(`${JSON.stringify(command)} is ${expected ? 'a force push' : 'not a force push'}`, () => {
      expect(isForcePush(command)).toBe(expected)
    })
  }

  for (const command of knownLimits) {
    test(`known limit: ${command} is not caught`, () => {
      expect(isForcePush(command)).toBe(false)
    })
  }
})