Skip to content

livery.extensions.claude._tasks

livery.extensions.claude._tasks

The hook verbs, fm hooks.*: the guards an agent session's tooling runs.

The extension's plugin, mounted while a workspace lists the extension. Wired from .claude/settings.json through one shim (.claude/hooks/fm-hook.sh); each event arrives on stdin and the verdict is the exit code: 0 is quiet, 2 blocks the gated action with stderr as the agent's feedback. The shim propagates only the hook's own 2 and turns every other failure into 0, because a guard that cannot run must not deny.

Classes:

Name Description
ToolInput

What the agent handed the tool, as the hook event carries it.

HookEvent

One Claude Code hook event, parsed from stdin.

Functions:

Name Description
pre_bash

Refuse the Bash commands that succeed while silently breaking state.

post_edit

Run the fixers over the edited file; never block an edit.

stop

Block ending a turn whose last Bash result is a red fm verdict.

Attributes:

Name Type Description
hooks

hooks module-attribute

hooks = group('hooks', hidden=True, help='Agent lifecycle hooks (stdin-driven)')

ToolInput dataclass

ToolInput(file_path: str = '', command: str = '')

What the agent handed the tool, as the hook event carries it.

Attributes:

Name Type Description
file_path str
command str

file_path class-attribute instance-attribute

file_path: str = ''

command class-attribute instance-attribute

command: str = ''

HookEvent dataclass

HookEvent(tool_input: ToolInput = ToolInput(), stop_hook_active: bool = False, session_id: str = '', transcript_path: str = '')

One Claude Code hook event, parsed from stdin.

Attributes:

Name Type Description
tool_input ToolInput
stop_hook_active bool
session_id str
transcript_path str

tool_input class-attribute instance-attribute

tool_input: ToolInput = dataclasses.field(default_factory=ToolInput)

stop_hook_active class-attribute instance-attribute

stop_hook_active: bool = False

session_id class-attribute instance-attribute

session_id: str = ''

transcript_path class-attribute instance-attribute

transcript_path: str = ''

pre_bash

pre_bash(event: Annotated[HookEvent, stdin]) -> None

Refuse the Bash commands that succeed while silently breaking state.

The two: a footman gate piped into tail/head, and a git push of a branch that conflicts with origin/main. Ported from footman's own loop.

The pipe guard. A gate's exit code is its verdict, and a pipe replaces it with the filter's, so fm check | tail -4 reports 0 whatever happened and prints the step summary while the failing step scrolls past above. A red gate has been reported green here exactly that way.

The push guard. Agent sessions share this repository, so main moves while a branch is being built, and a branch pushed from a stale base opens a conflicting pull request for which GitHub cannot build its test-merge and therefore spawns no CI at all: no red X, no checks, just an absence nothing points at. The guard runs the same test-merge locally (git merge-tree --write-tree) before letting the push through. Tag pushes, deletions, and pushes of main itself pass untouched.

Both are deliberately narrow. Command separators split first, so fm check && echo done | tail stays legal; quoted spans are data, so rg "fm check" | head passes. Nudges, not a sandbox.

Source code in packages/extensions/claude/src/livery/extensions/claude/_tasks.py
@hooks.task(name="pre-bash")
def pre_bash(event: Annotated[HookEvent, stdin]) -> None:
    """Refuse the Bash commands that succeed while silently breaking state.

    The two: a footman gate piped into tail/head, and a git push of a
    branch that conflicts with origin/main. Ported from footman's own
    loop.

    **The pipe guard.** A gate's exit code is its verdict, and a pipe
    replaces it with the filter's, so `fm check | tail -4` reports 0
    whatever happened and prints the step summary while the failing step
    scrolls past above. A red gate has been reported green here exactly
    that way.

    **The push guard.** Agent sessions share this repository, so main moves
    while a branch is being built, and a branch pushed from a stale base
    opens a conflicting pull request for which GitHub cannot build its
    test-merge and therefore spawns no CI at all: no red X, no checks, just
    an absence nothing points at. The guard runs the same test-merge
    locally (git merge-tree --write-tree) before letting the push through.
    Tag pushes, deletions, and pushes of main itself pass untouched.

    Both are deliberately narrow. Command separators split first, so
    `fm check && echo done | tail` stays legal; quoted spans are data, so
    `rg "fm check" | head` passes. Nudges, not a sandbox.
    """
    segments = re.split(r";|&&|\|\|", event.tool_input.command)
    blind = [_QUOTED.sub('""', segment) for segment in segments]
    if any(
        _TRUNCATES.search(segment[match.end() :])
        for segment in blind
        if (match := _runs_runner().search(segment)) is not None
    ):
        fail(
            "piping a footman command into tail/head replaces its exit code "
            "with the filter's and hides the failing step - a red gate has "
            "been reported green here that way. Run it unpiped and read the "
            "exit code; to keep the output short, redirect to a file and "
            "slice the file.",
            code=2,
        )
    for segment in blind:
        push = _PUSHES.search(segment)
        if push is None or _PUSH_EXEMPT.search(segment):
            continue
        repo = push.group(1)  # a quoted -C path was blinded; probe the cwd then
        where = None if repo in (None, '""') else repo
        if any(_push_conflicts(where, ref) for ref in _pushed_refs(push.group(2))):
            fail(
                "git push refused: this branch conflicts with origin/main. A "
                "conflicting PR spawns no CI at all - GitHub cannot build its "
                "test-merge, so there is no red X, no checks, just silence. "
                f"Align the branch with `{footman.prog()} sync`, re-run the gate,"
                " then push.",
                code=2,
            )

post_edit

post_edit(event: Annotated[HookEvent, stdin]) -> None

Run the fixers over the edited file; never block an edit.

Best-effort by design: every outcome exits 0 and says nothing, because a formatter problem must never block an edit. The gate, not the hook, is the arbiter; this only saves round trips.

Imports are never removed here: an edit in flight legitimately adds an import before the code that uses it, and a hook firing between the two edits would delete it (measured, twice in one session). The full clean, unused imports included, belongs to the stop hook and the gate.

Source code in packages/extensions/claude/src/livery/extensions/claude/_tasks.py
@hooks.task(name="post-edit")
def post_edit(event: Annotated[HookEvent, stdin]) -> None:
    """Run the fixers over the edited file; never block an edit.

    Best-effort by design: every outcome exits 0 and says nothing,
    because a formatter problem must never block an edit. The gate,
    not the hook, is the arbiter; this only saves round trips.

    Imports are never removed here: an edit in flight legitimately
    adds an import before the code that uses it, and a hook firing
    between the two edits would delete it (measured, twice in one
    session). The full clean, unused imports included, belongs to
    the stop hook and the gate.
    """
    import contextlib
    import io

    from livery.workshop import fix_files

    path = event.tool_input.file_path
    if not path or not Path(path).is_file():
        return
    # Through the gate's walk, never a tool: every fixer whose claims
    # reach the file runs over it, a python formatter's for python,
    # clang-format's for C++, an extension's for its own files; a file
    # no claim reaches is the walk's no-op, not the hook's business.
    with (
        contextlib.suppress(Exception, SystemExit),
        contextlib.redirect_stdout(io.StringIO()),
    ):
        fix_files((path,), safe=True)

stop

stop(event: Annotated[HookEvent, stdin]) -> int

Block ending a turn whose last Bash result is a red fm verdict.

stop_hook_active (the harness's retry marker) always passes, so a deliberate stop with a reported failure costs one nudge and never loops.

Source code in packages/extensions/claude/src/livery/extensions/claude/_tasks.py
@hooks.task(name="stop")
def stop(event: Annotated[HookEvent, stdin]) -> int:
    """Block ending a turn whose last Bash result is a red fm verdict.

    ``stop_hook_active`` (the harness's retry marker) always passes,
    so a deliberate stop with a reported failure costs one nudge and
    never loops.
    """
    if event.stop_hook_active:
        return 0
    transcript = Path(event.transcript_path)
    if not transcript.is_file():
        return 0
    if not _FAIL.search(_last_bash_result(transcript)):
        return 0
    sys.stderr.write(
        "The last Bash result in this turn is a FAILED fm command."
        " Fix it now, or - if the failure is deliberate and already"
        " reported to the user in your final message - stop again to"
        " proceed.\n"
    )
    return 2