feat(validator): add function hooking via MinHook and vtable swapping

Two-layer hooking system replaces the failed retour-rs approach:
- VTable hooks: swap function pointers in .rdata for CTask virtual methods
- MinHook inline hooks: FrontendChangeScreen, CTask::Constructor,
CGameTask::Constructor — handles SEH prologues correctly

Also adds .cargo/config.toml to default target to i686-pc-windows-msvc.

Tested in-game: all hooks fire correctly, game runs normally.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.cargo/config.toml

@@ -0,0 +1,2 @@
+[build]
+target = "i686-pc-windows-msvc"

Cargo.lock

@@ -2,12 +2,50 @@
 # It is not intended for manual editing.
 version = 4
 
+[[package]]
+name = "cc"
+version = "1.2.56"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aebf35691d1bfb0ac386a69bac2fde4dd276fb618cf8bf4f5318fe285e821bb2"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+
 [[package]]
 name = "libc"
 version = "0.2.182"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6800badb6cb2082ffd7b6a67e6125bb39f18782f793520caee8cb8846be06112"
 
+[[package]]
+name = "log"
+version = "0.4.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
+
+[[package]]
+name = "minhook"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "455e088cb1600ffa5f1524c9702c9eeb0ba3604e0f4932efa165b99973272a8d"
+dependencies = [
+ "cc",
+ "tracing",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42f5e15c9953c5e4ccceeb2e7382a716482c34515315f7b03532b8b4e8393d2d"
+
 [[package]]
 name = "openwa-harness"
 version = "0.1.0"
@@ -25,9 +63,90 @@ version = "0.1.0"
 name = "openwa-validator"
 version = "0.1.0"
 dependencies = [
+ "minhook",
  "openwa-types",
+ "windows-sys",
 ]
 
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "tracing"
+version = "0.1.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
+dependencies = [
+ "log",
+ "pin-project-lite",
+ "tracing-attributes",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-attributes"
+version = "0.1.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tracing-core"
+version = "0.1.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
 [[package]]
 name = "windows-sys"
 version = "0.59.0"

crates/openwa-validator/Cargo.toml

@@ -9,3 +9,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 openwa-types = { path = "../openwa-types" }
+minhook = "0.9"
+
+[target.'cfg(target_os = "windows")'.dependencies]
+windows-sys = { version = "0.59", features = ["Win32_System_Memory"] }

crates/openwa-validator/src/hooks/detour.rs

@@ -0,0 +1,124 @@
+//! MinHook-based inline hooking for arbitrary functions.
+//!
+//! Uses MinHook to create trampolines that correctly handle SEH prologues
+//! (which retour-rs could not). This allows hooking constructors and free
+//! functions that aren't in vtables.
+
+use std::ffi::c_void;
+use std::sync::atomic::{AtomicU32, Ordering};
+
+use minhook::MinHook;
+
+use crate::{log_line, rb};
+use openwa_types::address::va;
+
+/// Install an inline hook at a Ghidra address, redirecting to `detour_fn`.
+/// Returns the trampoline pointer for calling the original.
+unsafe fn install_hook(ghidra_addr: u32, detour_fn: *const (), name: &str) -> Result<u32, String> {
+    let target = rb(ghidra_addr) as *mut c_void;
+    let detour = detour_fn as *mut c_void;
+
+    let trampoline = MinHook::create_hook(target, detour)
+        .map_err(|e| format!("MinHook create_hook failed for {name}: {e}"))?;
+
+    MinHook::enable_hook(target)
+        .map_err(|e| format!("MinHook enable_hook failed for {name}: {e}"))?;
+
+    let trampoline_addr = trampoline as u32;
+    let _ = log_line(&format!(
+        "  [MH] {name}: target 0x{:08X} (ghidra 0x{ghidra_addr:08X}), trampoline 0x{trampoline_addr:08X}",
+        target as u32
+    ));
+
+    Ok(trampoline_addr)
+}
+
+// ---------------------------------------------------------------------------
+// FrontendChangeScreen hook
+// ---------------------------------------------------------------------------
+
+static ORIG_FRONTEND_CHANGE_SCREEN: AtomicU32 = AtomicU32::new(0);
+
+/// Hook for FrontendChangeScreen (0x447A20).
+/// Called on every menu screen transition. Logs the screen ID.
+///
+/// RET 0x4 → stdcall with 1 param (screen_id). ESI = dialog this (implicit).
+unsafe extern "stdcall" fn hook_frontend_change_screen(screen_id: u32) {
+    let _ = log_line(&format!("[HOOK] FrontendChangeScreen(screen_id={screen_id})"));
+    let orig: unsafe extern "stdcall" fn(u32) =
+        core::mem::transmute(ORIG_FRONTEND_CHANGE_SCREEN.load(Ordering::Relaxed));
+    orig(screen_id);
+}
+
+// ---------------------------------------------------------------------------
+// CTask::Constructor hook
+// ---------------------------------------------------------------------------
+
+static ORIG_CTASK_CONSTRUCTOR: AtomicU32 = AtomicU32::new(0);
+
+/// Hook for CTask::Constructor (0x5625A0).
+/// stdcall(this, parent, class_type) -> this
+unsafe extern "stdcall" fn hook_ctask_constructor(this: u32, parent: u32, class_type: u32) -> u32 {
+    let orig: unsafe extern "stdcall" fn(u32, u32, u32) -> u32 =
+        core::mem::transmute(ORIG_CTASK_CONSTRUCTOR.load(Ordering::Relaxed));
+    let result = orig(this, parent, class_type);
+    // Log after calling original (so vtable is set)
+    let _ = log_line(&format!(
+        "[HOOK] CTask::ctor(this=0x{this:08X}, parent=0x{parent:08X}, type={class_type}) -> 0x{result:08X}"
+    ));
+    result
+}
+
+// ---------------------------------------------------------------------------
+// CGameTask::Constructor hook
+// ---------------------------------------------------------------------------
+
+static ORIG_CGAMETASK_CONSTRUCTOR: AtomicU32 = AtomicU32::new(0);
+
+/// Hook for CGameTask::Constructor (0x4FED50).
+/// RET 0x10 → stdcall with 4 params: (this, parent, param3, param4)
+/// param3/param4 are stored at this+0x30/this+0x38 (likely initial position)
+unsafe extern "stdcall" fn hook_cgametask_constructor(this: u32, parent: u32, param3: u32, param4: u32) -> u32 {
+    let orig: unsafe extern "stdcall" fn(u32, u32, u32, u32) -> u32 =
+        core::mem::transmute(ORIG_CGAMETASK_CONSTRUCTOR.load(Ordering::Relaxed));
+    let result = orig(this, parent, param3, param4);
+    let _ = log_line(&format!(
+        "[HOOK] CGameTask::ctor(this=0x{this:08X}, parent=0x{parent:08X}) -> 0x{result:08X}"
+    ));
+    result
+}
+
+// ---------------------------------------------------------------------------
+// Installation
+// ---------------------------------------------------------------------------
+
+pub fn install() -> Result<(), String> {
+    unsafe {
+        // FrontendChangeScreen — called on every menu navigation
+        let trampoline = install_hook(
+            va::FRONTEND_CHANGE_SCREEN,
+            hook_frontend_change_screen as *const (),
+            "FrontendChangeScreen",
+        )?;
+        ORIG_FRONTEND_CHANGE_SCREEN.store(trampoline, Ordering::Relaxed);
+
+        // CTask::Constructor — base class constructor
+        let trampoline = install_hook(
+            va::CTASK_CONSTRUCTOR,
+            hook_ctask_constructor as *const (),
+            "CTask::Constructor",
+        )?;
+        ORIG_CTASK_CONSTRUCTOR.store(trampoline, Ordering::Relaxed);
+
+        // CGameTask::Constructor — game entity constructor
+        let trampoline = install_hook(
+            va::CGAMETASK_CONSTRUCTOR,
+            hook_cgametask_constructor as *const (),
+            "CGameTask::Constructor",
+        )?;
+        ORIG_CGAMETASK_CONSTRUCTOR.store(trampoline, Ordering::Relaxed);
+    }
+
+    let _ = log_line("  3 inline hooks installed via MinHook");
+    Ok(())
+}

crates/openwa-validator/src/hooks/mod.rs

@@ -0,0 +1,19 @@
+pub mod vtable;
+pub mod detour;
+
+use crate::log_line;
+
+/// Install all hooks. Called from run_validation() after rebase init.
+pub fn install_all() -> Result<(), String> {
+    let _ = log_line("");
+    let _ = log_line("--- Installing Hooks ---");
+
+    // VTable hooks (pure Rust, no dependencies)
+    vtable::install()?;
+
+    // Inline hooks via MinHook (for constructors and free functions)
+    detour::install()?;
+
+    let _ = log_line("  All hooks installed.");
+    Ok(())
+}

crates/openwa-validator/src/hooks/vtable.rs

@@ -0,0 +1,126 @@
+//! VTable hooking — swap function pointers in vtable memory.
+//!
+//! This is the simplest hooking approach: write a new function pointer
+//! into a vtable slot and save the original. No trampoline, no prologue
+//! analysis, no external dependencies.
+
+use std::sync::atomic::{AtomicU32, Ordering};
+
+use crate::{log_line, rb};
+use openwa_types::address::va;
+
+#[cfg(target_os = "windows")]
+use windows_sys::Win32::System::Memory::{VirtualProtect, PAGE_READWRITE};
+
+/// A single vtable hook — remembers the slot address and original pointer.
+pub struct VtableHook {
+    #[allow(dead_code)]
+    slot_addr: *mut u32,
+    original_fn: u32,
+    #[allow(dead_code)]
+    name: &'static str,
+}
+
+// VtableHook contains a raw pointer but is only used from the main thread
+unsafe impl Send for VtableHook {}
+unsafe impl Sync for VtableHook {}
+
+impl VtableHook {
+    /// Install a vtable hook at `vtable_ghidra_addr + slot_index * 4`.
+    ///
+    /// # Safety
+    /// - `vtable_ghidra_addr` must be a valid vtable base in .rdata
+    /// - `hook_fn` must match the calling convention of the original method
+    #[cfg(target_os = "windows")]
+    pub unsafe fn install(
+        vtable_ghidra_addr: u32,
+        slot_index: usize,
+        hook_fn: u32,
+        name: &'static str,
+    ) -> Result<Self, String> {
+        let slot_addr = rb(vtable_ghidra_addr + (slot_index as u32) * 4) as *mut u32;
+
+        // Make the vtable slot writable
+        let mut old_protect: u32 = 0;
+        let ok = VirtualProtect(slot_addr as *mut _, 4, PAGE_READWRITE, &mut old_protect);
+        if ok == 0 {
+            return Err(format!("VirtualProtect failed for {name} at 0x{:08X}", slot_addr as u32));
+        }
+
+        // Read original and write hook
+        let original_fn = *slot_addr;
+        *slot_addr = hook_fn;
+
+        // Restore protection
+        VirtualProtect(slot_addr as *mut _, 4, old_protect, &mut old_protect);
+
+        let _ = log_line(&format!(
+            "  [VT] {name}: slot 0x{:08X}, orig 0x{original_fn:08X} -> hook 0x{hook_fn:08X}",
+            slot_addr as u32
+        ));
+
+        Ok(VtableHook { slot_addr, original_fn, name })
+    }
+
+    /// Get the original function pointer (for calling the original from the hook).
+    pub fn original(&self) -> u32 {
+        self.original_fn
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Installed hooks — stored globally so originals can be called
+// ---------------------------------------------------------------------------
+
+/// Original CTask::ProcessFrame function pointer (thiscall: ECX = this)
+static ORIG_CTASK_PROCESS_FRAME: AtomicU32 = AtomicU32::new(0);
+
+/// Hook for CTask::ProcessFrame (vtable slot 7).
+/// thiscall convention: ECX = this. We use fastcall (ECX = arg1, EDX = arg2).
+unsafe extern "fastcall" fn hook_ctask_process_frame(this: u32, _edx: u32) -> u32 {
+    // Call original
+    let orig: unsafe extern "fastcall" fn(u32, u32) -> u32 =
+        core::mem::transmute(ORIG_CTASK_PROCESS_FRAME.load(Ordering::Relaxed));
+    orig(this, 0)
+}
+
+/// Original CTask::HandleMessage function pointer
+static ORIG_CTASK_HANDLE_MESSAGE: AtomicU32 = AtomicU32::new(0);
+
+/// Hook for CTask::HandleMessage (vtable slot 2).
+/// thiscall(this, msg_id, param) — ECX = this, two stack params
+unsafe extern "fastcall" fn hook_ctask_handle_message(this: u32, _edx: u32, msg_id: u32, param: u32) -> u32 {
+    let orig: unsafe extern "fastcall" fn(u32, u32, u32, u32) -> u32 =
+        core::mem::transmute(ORIG_CTASK_HANDLE_MESSAGE.load(Ordering::Relaxed));
+    orig(this, 0, msg_id, param)
+}
+
+// ---------------------------------------------------------------------------
+// Installation
+// ---------------------------------------------------------------------------
+
+pub fn install() -> Result<(), String> {
+    unsafe {
+        // CTask::ProcessFrame — slot 7
+        let hook = VtableHook::install(
+            va::CTASK_VTABLE,
+            7,
+            hook_ctask_process_frame as *const () as u32,
+            "CTask::ProcessFrame",
+        )?;
+        ORIG_CTASK_PROCESS_FRAME.store(hook.original(), Ordering::Relaxed);
+
+        // CTask::HandleMessage — slot 2
+        let hook = VtableHook::install(
+            va::CTASK_VTABLE,
+            2,
+            hook_ctask_handle_message as *const () as u32,
+            "CTask::HandleMessage",
+        )?;
+        ORIG_CTASK_HANDLE_MESSAGE.store(hook.original(), Ordering::Relaxed);
+
+        let _ = log_line("  2 vtable hooks installed");
+    }
+
+    Ok(())
+}

crates/openwa-validator/src/lib.rs

@@ -3,6 +3,8 @@
 use std::ffi::c_void;
 use std::sync::atomic::{AtomicU32, Ordering};
 
+mod hooks;
+
 use openwa_types::address::va;
 use openwa_types::task::{CTask, CGameTask};
 use openwa_types::ddgame::DDGame;
@@ -18,7 +20,7 @@ static REBASE_DELTA: AtomicU32 = AtomicU32::new(0);
 
 /// Rebase a Ghidra VA to the actual runtime address.
 #[inline]
-fn rb(ghidra_addr: u32) -> u32 {
+pub(crate) fn rb(ghidra_addr: u32) -> u32 {
     ghidra_addr.wrapping_add(REBASE_DELTA.load(Ordering::Relaxed))
 }
 
@@ -59,7 +61,7 @@ unsafe extern "system" fn DllMain(
 // Logging
 // ---------------------------------------------------------------------------
 
-fn log_line(msg: &str) -> std::io::Result<()> {
+pub(crate) fn log_line(msg: &str) -> std::io::Result<()> {
     use std::io::Write;
     let mut f = std::fs::OpenOptions::new()
         .create(true)
@@ -504,8 +506,13 @@ fn run_validation() -> Result<(), Box<dyn std::error::Error>> {
     let _ = log_line("--- Static Validation Summary ---");
     let _ = log_line(&format!("  {}", result.summary_line()));
 
-    // 6. Hooks disabled — retour trampoline corrupts SEH prologue on these constructors
-    // Instead, use a polling thread to find DDGameWrapper after init completes
+    // 6. Install hooks (vtable + inline)
+    match hooks::install_all() {
+        Ok(()) => {}
+        Err(e) => { let _ = log_line(&format!("[ERROR] Hook installation failed: {}", e)); }
+    }
+
+    // 7. Deferred validation via polling (for DDGameWrapper — hooks don't cover this yet)
     let _ = log_line("");
     let _ = log_line("--- Deferred Validation (polling) ---");
     std::thread::spawn(move || {