Skip to content

Hook Host

Ryan Cole edited this page Nov 15, 2026 · 2 revisions

One Detours DLL that hooks any x64 or x86 (32-bit) program at the addresses pbeta found. No addresses in your code, and for logging or short-circuiting a function, no code at all. Full reference: harness/host/README.md.

pbeta repair ...          ->  repaired hook manifests (one per build)
pbeta host-config ...     ->  pbeta-host.toml
pbeta-launch pbeta-host.toml app.exe

On load, pbeta-host.dll hashes the exe it's in and attaches only the hooks listed for that build, each after its pattern matches. A build the config doesn't list gets no hooks. A hook in review stays listed for the build where it was verified, so it's never attached in the new one.

Build it with pwsh harness/host/build.ps1 (Installation), or pwsh harness/host/build.ps1 -Arch x86 for 32-bit programs (into target/host-x86).

Configure

pbeta host-config --hooks hooks.toml --hooks hooks.new.toml --analysis old.json --analysis new.json --out pbeta-host.toml

Pass every manifest of the release line. --analysis (from analyze --pdb) supplies PDB signatures for hooks without a prototype, so their arguments can be decoded.

Actions

Set with each hook's detour (Hook Manifest), then run host-config again:

detour On each call
log (or none) Logs the arguments and result; the original runs.
skip Logs the call; returns 0 without running the original.
return <n> Logs the call; returns n without running the original (integer or pointer results).
<file.dll>!<export> Your handler runs instead. The path is relative to the config's folder.

Built-in actions work for any prototype up to 12 parameters, except variadic functions, and up to 64 hooks per process (handlers don't count).

Handlers

A handler is only the function body:

#include <pbeta_handler.h>

PBETA_HOOK(int, SaveDocument, (Doc* doc, const wchar_t* path)) {
    pbeta_log("saving %ls", path);
    return PBETA_ORIGINAL(SaveDocument)(doc, path);
}

The prototype must match the hooked function exactly, and nothing checks it at load, so let pbeta write the declarations:

pbeta handler-stubs --hooks hooks.toml --hooks hooks.new.toml --analysis new.json --out handlers.cpp
cl /LD /I<repo>\target\host\include handlers.cpp

Each stub calls the original, so the DLL compiles and changes nothing until you edit a body. handler-stubs won't overwrite a file without --force.

Run

pbeta-launch [--log <file>] pbeta-host.toml app.exe [app args...]

The app starts suspended with the host in its import table, so hooks attach before its own code runs. The log defaults to pbeta-host.log next to the config. PBETA_HOST_CONFIG and PBETA_HOST_LOG set the same paths when the host is loaded some other way.

32-bit programs

Use the x86 build's pbeta-launch.exe and pbeta-host.dll. Run host-config with the build's analysis (--analysis): it marks an x86 build's entries abi = "win32", with each hook's calling convention and stack size. The x86 host refuses entries without the mark, and the x64 host entries with it.

  • skip and return <n> remove stack arguments as the convention says (__stdcall, __thiscall, __fastcall), so on x86 they need a prototype.
  • A handler uses the function's convention: PBETA_HOOK_CC in pbeta_handler.h. handler-stubs writes it for you (a __thiscall member as __fastcall with an unused edx).
  • pwsh harness/host/test.ps1 -Arch x86 runs the end-to-end test on a 32-bit test app, with __stdcall, __fastcall and __thiscall hooks.

Limits

  • x64 and x86. Attaching to a running process isn't built.
  • x86: the thunk copies 32 stack words when it calls the original, so host-config refuses built-in actions on functions with more than 128 bytes of stack arguments (a handler has no limit). Functions /LTCG compiled with a custom calling convention aren't supported.
  • The log is plain text, unbuffered: very hot functions slow the program.

Clone this wiki locally