Ghidrust provides a hyper fast, AI native reverse engineering platform built in Rust, inspired by Ghidra. Includes experimental GPU kernels to rapidly decompile large files, a decryption suite, and network monitor for packet to binary reverse engineering.
Enhance Ghidrust CLI with version command to display package version and tool surface.
oofz4bc6d105c4fb
diff --git a/README.md b/README.mdindex a3f386e..7be6e44 100644--- a/README.md+++ b/README.md@@ -392,6 +392,7 @@ MyProject/| `ghidrust analyzer-bench-matrix` | Print GPU strategy class per analyzer || `ghidrust rtti-gpu-bench <path> [--out FILE]` | CPU RTTI vs GPU `rtti_scan` || `ghidrust project create\|import\|list\|analyze\|export …` | Durable projects |+| `ghidrust version` / `--version` / `-V` `[--json]` | Package version + `tool_surface` (matches MCP / egui About) || `ghidrust mcp` | Stdio MCP server for agents |`--json` and `--out FILE` write UTF-8 **without BOM**. Prefer `--out` over shell redirection when filters contain `:` (Windows path hazard). Decompile status lines go to stderr only with `--verbose` (avoids PowerShell `NativeCommandError` noise when scripting).@@ -463,6 +464,8 @@ Note the absolute path to the binary, e.g. `C:\path\to\Ghidrust\target\release\g**Other MCP clients** — same pattern: command = absolute path to `ghidrust` / `ghidrust.exe`, args = `["mcp"]`. Restart the client after editing config.+After rebuild/restart, confirm the binary matches the skill: `ghidrust --version` (package + `tool_surface`), and MCP `server_info` / `tools/list` includes `process_list` and `server_info`. If those tools are missing, the client is still running a stale binary — rebuild and restart MCP; do not treat that as “live process unsupported.”+On Linux/macOS:```json@@ -480,6 +483,7 @@ On Linux/macOS:| Tool | Args | Purpose ||------|------|---------|+| `server_info` | — | Package `version`, monotonic `tool_surface`, features, live session_model || `load` | `path` **or** `project`+`file_id` | Load PE/ELF; `resolved_path`, `sections`, `section_notes` || `disassemble` | `path`, optional `addr`, `count` | Listing + containing-fn resolve + `decode_gaps` || `rtti` | `path` | Full RTTI recover dump |@@ -510,7 +514,9 @@ On Linux/macOS:#### Live process (Windows)-Attach read-only (`PROCESS_VM_READ`): `process list` → `attach <pid>` → `modules` → `resolve --module NAME --rva HEX` (`static_to_live`) → `read --addr LIVE --size N` → optional `regions` / `detach`. Short reads and access denied are explicit errors. Bytes ≠ recovered types — do not invent structs from live reads. GUI: Debugger → Targets / Modules / Memory Bytes / Regions / Static Mappings.+Attach read-only (`PROCESS_VM_READ`): `process list` → `attach <pid>` → `modules` → `resolve --module NAME --rva HEX` (`static_to_live`) → `read --addr LIVE --size N` → optional `regions` / `detach`. Multi-step attach **must** use the long-lived MCP (or GUI) process — CLI `ghidrust process` cannot reuse `session_id` across separate spawns. Short reads and access denied are explicit errors. Bytes ≠ recovered types — do not invent structs from live reads. GUI: Debugger → Targets / Modules / Memory Bytes / Regions / Static Mappings.++Versioning: `ghidrust --version`, MCP `initialize`/`server_info`, and egui Help → About / window title all report the same workspace package version. Agents also check `tool_surface` (minimum `2` for live process + artifacts).#### Analysis artifactsdiff --git a/crates/ghidrust-cli/src/main.rs b/crates/ghidrust-cli/src/main.rsindex 3569bec..d92edfd 100644--- a/crates/ghidrust-cli/src/main.rs+++ b/crates/ghidrust-cli/src/main.rs@@ -17,6 +17,7 @@ use ghidrust_decomp::decompile_entry;use ghidrust_il2cpp::{classify_at, correlate, filter_entries, find_resolve_stubs, follow_stub_target,is_resolve_stub_va, resolve_icalls_path, stub_matches_filter, to_script_json, Il2CppMetadata,+ ResolveStub,};use ghidrust_unity_inventory::inventory_path;use serde::Serialize;@@ -27,6 +28,128 @@ use std::path::{Path, PathBuf};use std::process::ExitCode;use std::time::Instant;+/// Workspace package version — same string as MCP `serverInfo` and egui About.+const PACKAGE_VERSION: &str = env!("CARGO_PKG_VERSION");++/// Monotonic MCP tool-surface contract. Bump when tools are added/removed/renamed+/// or required args change in a breaking way. Skill documents a minimum.+/// `2` = live process + artifacts + inventory / tree / rtti_query surface.+const TOOL_SURFACE_VERSION: u32 = 2;++fn package_version() -> &'static str {+ PACKAGE_VERSION+}++fn server_info_json() -> Value {+ json!({+ "name": "ghidrust",+ "version": package_version(),+ "tool_surface": TOOL_SURFACE_VERSION,+ "features": [+ "live_process",+ "artifacts",+ "il2cpp",+ "inventory",+ "rtti_query",+ "list_tree",+ "decompile_stage1"+ ],+ "live_process": {+ "tools": [+ "process_list",+ "process_attach",+ "process_detach",+ "process_modules",+ "process_read",+ "process_resolve",+ "process_regions"+ ],+ "session_model": "in_process_mcp",+ "note": "Attach sessions live in the long-lived MCP (or GUI) process. CLI one-shot `ghidrust process` cannot reuse session_id across separate spawns."+ }+ })+}++/// Structured escalation when offline `follow_stub` cannot yield a real method body.+fn live_process_next_steps() -> Value {+ json!([+ "process_list",+ "process_attach",+ "process_modules",+ "process_resolve (module + method RVA from il2cpp_map)",+ "process_read",+ "optional process_regions / process_detach"+ ])+}++/// True when a followed stub target looks like a tiny trampoline/invoker, not a real body.+fn looks_like_trampoline(prog: &Program, target: u64) -> bool {+ if let Some(f) = prog.analysis.functions.iter().find(|f| f.entry == target) {+ let size = f.end.saturating_sub(f.entry);+ if size > 0 && size <= 32 {+ return true;+ }+ }+ match disassemble_range_opts(prog, target, 8, true) {+ Ok(range) => {+ let insns = &range.insns;+ if insns.len() <= 5 {+ let text = insns+ .iter()+ .map(|i| i.mnemonic.to_ascii_lowercase())+ .collect::<Vec<_>>()+ .join(" ");+ text.contains("jmp") || text.contains("ret") || insns.len() <= 3+ } else {+ false+ }+ }+ Err(_) => false,+ }+}++fn build_follow_stub_meta(prog: &Program, from: u64, stub: &ResolveStub) -> (Option<u64>, Value) {+ if let Some(target) = follow_stub_target(prog, stub) {+ if looks_like_trampoline(prog, target) {+ (+ Some(target),+ json!({+ "status": "trampoline_or_invoker",+ "from": format!("{from:#x}"),+ "to": format!("{target:#x}"),+ "slot_va": stub.slot_va.map(|s| format!("{s:#x}")),+ "icall_name": stub.icall_name,+ "note": "followed target looks like a trampoline/invoker — not a full managed body; use live process for runtime fields",+ "next_steps": live_process_next_steps(),+ }),+ )+ } else {+ (+ Some(target),+ json!({+ "status": "resolved",+ "from": format!("{from:#x}"),+ "to": format!("{target:#x}"),+ "slot_va": stub.slot_va.map(|s| format!("{s:#x}")),+ "icall_name": stub.icall_name,+ }),+ )+ }+ } else {+ (+ None,+ json!({+ "status": "runtime_unresolved",+ "from": format!("{from:#x}"),+ "slot_va": stub.slot_va.map(|s| format!("{s:#x}")),+ "icall_name": stub.icall_name,+ "note": "empty/runtime slot; offline follow_stub cannot yield method body",+ "next_steps": live_process_next_steps(),+ }),+ )+ }+}+fn main() -> ExitCode {let mut args: Vec<String> = env::args().skip(1).collect();if args.is_empty() {@@ -41,6 +164,18 @@ fn main() -> ExitCode {print_help();ExitCode::SUCCESS}+ "version" | "--version" | "-V" => {+ if json_mode {+ println!(+ "{}",+ serde_json::to_string_pretty(&server_info_json()).unwrap()+ );+ } else {+ println!("ghidrust {}", package_version());+ println!("tool_surface={}", TOOL_SURFACE_VERSION);+ }+ ExitCode::SUCCESS+ }"load" => cmd_load(&args[1..], json_mode),"disasm" | "disassemble" => cmd_disasm(&args[1..], json_mode),"bytes" | "dump" => cmd_bytes(&args[1..], json_mode),@@ -97,6 +232,7 @@ fn print_help() {eprintln!("ghidrust — AI-native reverse-engineering (CodeBrowser headless)\n\n\Usage:\n\+ ghidrust version | --version | -V [--json]\n\ghidrust load <path|--project DIR --file-id ID> [--out FILE] [--json]\n\ghidrust disasm <path> [--addr <hex>] [--count N] [--skip-bad] [--out FILE] [--json]\n\ghidrust bytes <path> --addr HEX [--count N] [--out FILE] [--json]\n\@@ -2018,36 +2154,22 @@ fn cmd_decompile(args: &[String], json: bool) -> ExitCode {let mut follow_meta: Option<Value> = None;if follow_stub {if let Some(stub) = classify_at(&prog, va) {- if let Some(target) = follow_stub_target(&prog, &stub) {- if verbose {+ let (new_va, fm) = build_follow_stub_meta(&prog, va, &stub);+ if let Some(status) = fm.get("status").and_then(|s| s.as_str()) {+ if verbose || (!json && status != "resolved") {eprintln!(- "follow-stub: {:#x} -> {:#x} ({})",- va,- target,- stub.icall_name.as_deref().unwrap_or("resolve")+ "follow-stub: {va:#x} {status}{}",+ fm.get("to")+ .and_then(|t| t.as_str())+ .map(|t| format!(" -> {t}"))+ .unwrap_or_default());}- follow_meta = Some(json!({- "status": "resolved",- "from": format!("{va:#x}"),- "to": format!("{target:#x}"),- "slot_va": stub.slot_va.map(|s| format!("{s:#x}")),- "icall_name": stub.icall_name,- }));- va = target;- } else {- let note = "resolve slot empty or unmapped — filled at runtime";- if verbose || !json {- eprintln!("follow-stub: {va:#x} runtime_unresolved ({note})");- }- follow_meta = Some(json!({- "status": "runtime_unresolved",- "from": format!("{va:#x}"),- "slot_va": stub.slot_va.map(|s| format!("{s:#x}")),- "icall_name": stub.icall_name,- "note": note,- }));}+ if let Some(t) = new_va {+ va = t;+ }+ follow_meta = Some(fm);}}if stage1 {@@ -2764,6 +2886,11 @@ struct ToolDef {fn tool_defs() -> Vec<ToolDef> {vec![+ ToolDef {+ name: "server_info",+ description: "Package version, tool_surface, and feature flags (check before assuming live process / artifacts)",+ input_schema: json!({ "type": "object", "properties": {} }),+ },ToolDef {name: "load",description: "Load a PE or ELF binary (path OR project+file_id) and return sections + section_notes",@@ -3215,6 +3342,18 @@ fn tool_defs() -> Vec<ToolDef> {]}+fn mcp_write(stdout: &mut impl Write, resp: &Value) -> bool {+ // MCP stdio: one compact JSON object per line (no embedded newlines).+ let Ok(line) = serde_json::to_string(resp) else {+ return false;+ };+ if writeln!(stdout, "{line}").is_err() {+ return false;+ }+ stdout.flush().ok();+ true+}+fn run_mcp_stdio() -> ExitCode {let stdin = io::stdin();let mut stdout = io::stdout();@@ -3233,7 +3372,9 @@ fn run_mcp_stdio() -> ExitCode {Ok(v) => v,Err(e) => {let err = json!({"jsonrpc":"2.0","id":null,"error":{"code":-32700,"message":e.to_string()}});- writeln!(stdout, "{err}").ok();+ if !mcp_write(&mut stdout, &err) {+ return ExitCode::FAILURE;+ }continue;}};@@ -3242,20 +3383,45 @@ fn run_mcp_stdio() -> ExitCode {let params = req.get("params").cloned().unwrap_or(json!({}));let resp = match method {- "initialize" => json!({- "jsonrpc": "2.0",- "id": id,- "result": {- "protocolVersion": "2024-11-05",- "capabilities": { "tools": {} },- "serverInfo": { "name": "ghidrust", "version": "0.1.0" }- }- }),- "tools/list" | "list_tools" => json!({- "jsonrpc": "2.0",- "id": id,- "result": { "tools": tool_defs() }- }),+ "initialize" => {+ // Echo a client-requested protocol version when present; Cursor+ // currently sends 2025-11-25. Fall back to a stable baseline.+ let client_proto = params+ .get("protocolVersion")+ .and_then(|v| v.as_str())+ .unwrap_or("2024-11-05");+ let proto = match client_proto {+ "2025-11-25" | "2025-06-18" | "2025-03-26" | "2024-11-05" => client_proto,+ _ => "2024-11-05",+ };+ json!({+ "jsonrpc": "2.0",+ "id": id,+ "result": {+ "protocolVersion": proto,+ "capabilities": { "tools": { "listChanged": false } },+ "serverInfo": {+ "name": "ghidrust",+ "version": package_version(),+ "toolSurface": TOOL_SURFACE_VERSION+ }+ }+ })+ }+ "tools/list" | "list_tools" => {+ // Serialize tools explicitly so the line stays compact and+ // schema field names match MCP (inputSchema).+ let tools: Vec<Value> = tool_defs()+ .into_iter()+ .filter_map(|t| serde_json::to_value(t).ok())+ .collect();+ eprintln!("mcp tools/list → {} tools (tool_surface={})", tools.len(), TOOL_SURFACE_VERSION);+ json!({+ "jsonrpc": "2.0",+ "id": id,+ "result": { "tools": tools }+ })+ }"tools/call" | "call_tool" => match call_tool(¶ms) {Ok(content) => json!({"jsonrpc": "2.0",@@ -3286,10 +3452,9 @@ fn run_mcp_stdio() -> ExitCode {"error": { "code": -32601, "message": format!("method not found: {method}") }}),};- if writeln!(stdout, "{resp}").is_err() {+ if !mcp_write(&mut stdout, &resp) {return ExitCode::FAILURE;}- stdout.flush().ok();}ExitCode::SUCCESS}@@ -3302,6 +3467,7 @@ fn call_tool(params: &Value) -> Result<String, String> {let args = params.get("arguments").cloned().unwrap_or(json!({}));match name {+ "server_info" => Ok(serde_json::to_string_pretty(&server_info_json()).unwrap()),"artifact_get" => {let id = args.get("id")@@ -3910,24 +4076,11 @@ fn call_tool(params: &Value) -> Result<String, String> {let mut follow_meta: Option<Value> = None;if follow_stub {if let Some(stub) = classify_at(&prog, va) {- if let Some(target) = follow_stub_target(&prog, &stub) {- follow_meta = Some(json!({- "status": "resolved",- "from": format!("{va:#x}"),- "to": format!("{target:#x}"),- "slot_va": stub.slot_va.map(|s| format!("{s:#x}")),- "icall_name": stub.icall_name,- }));- va = target;- } else {- follow_meta = Some(json!({- "status": "runtime_unresolved",- "from": format!("{va:#x}"),- "slot_va": stub.slot_va.map(|s| format!("{s:#x}")),- "icall_name": stub.icall_name,- "note": "resolve slot empty or unmapped — filled at runtime",- }));+ let (new_va, fm) = build_follow_stub_meta(&prog, va, &stub);+ if let Some(t) = new_va {+ va = t;}+ follow_meta = Some(fm);}}let conv = if prog.format.to_ascii_lowercase().contains("pe") {diff --git a/crates/ghidrust-cli/tests/cli_mcp.rs b/crates/ghidrust-cli/tests/cli_mcp.rsindex f7b4087..6ae4a68 100644--- a/crates/ghidrust-cli/tests/cli_mcp.rs+++ b/crates/ghidrust-cli/tests/cli_mcp.rs@@ -178,3 +178,68 @@ fn mcp_lists_new_lookup_tools() {assert!(s.contains(tool), "missing {tool} in {s}");}}++#[test]+fn cli_version_matches_package() {+ let out = bin().args(["--version"]).output().expect("version");+ assert!(out.status.success(), "stderr={}", String::from_utf8_lossy(&out.stderr));+ let s = String::from_utf8_lossy(&out.stdout);+ assert!(+ s.contains(env!("CARGO_PKG_VERSION")),+ "missing package version in {s}"+ );+ assert!(s.contains("tool_surface="), "{s}");+}++#[test]+fn mcp_server_info_and_live_tools() {+ let mut child = bin()+ .arg("mcp")+ .stdin(Stdio::piped())+ .stdout(Stdio::piped())+ .stderr(Stdio::piped())+ .spawn()+ .expect("spawn mcp");+ let mut stdin = child.stdin.take().unwrap();+ let reqs = format!(+ "{}\n{}\n{}\n",+ json!({"jsonrpc":"2.0","id":1,"method":"initialize","params":{+ "protocolVersion":"2024-11-05",+ "capabilities":{},+ "clientInfo":{"name":"test","version":"0"}+ }}),+ json!({"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}),+ json!({"jsonrpc":"2.0","id":3,"method":"tools/call","params":{+ "name":"server_info","arguments":{}+ }}),+ );+ stdin.write_all(reqs.as_bytes()).unwrap();+ drop(stdin);+ let out = child.wait_with_output().unwrap();+ assert!(out.status.success(), "stderr={}", String::from_utf8_lossy(&out.stderr));+ let s = String::from_utf8_lossy(&out.stdout);+ let ver = env!("CARGO_PKG_VERSION");+ assert!(s.contains(ver), "initialize/server_info missing version {ver}: {s}");+ assert!(+ s.contains("toolSurface") || s.contains("tool_surface"),+ "missing tool_surface in {s}"+ );+ for tool in [+ "server_info",+ "process_list",+ "process_attach",+ "process_resolve",+ "process_read",+ "artifact_query",+ "inventory",+ ] {+ assert!(s.contains(tool), "missing {tool} in {s}");+ }+ // tool_surface must be at least 2 (not a placeholder zero)+ assert!(+ s.contains("\"toolSurface\":2")+ || s.contains("\"tool_surface\": 2")+ || s.contains("\"tool_surface\":2"),+ "expected tool_surface >= 2 in {s}"+ );+}diff --git a/crates/ghidrust-gui/src/main.rs b/crates/ghidrust-gui/src/main.rsindex 4805937..bf045ad 100644--- a/crates/ghidrust-gui/src/main.rs+++ b/crates/ghidrust-gui/src/main.rs@@ -176,14 +176,15 @@ struct AnalysisJob {}fn main() -> eframe::Result<()> {+ let title = format!("Ghidrust {} CodeBrowser", env!("CARGO_PKG_VERSION"));let opts = eframe::NativeOptions {viewport: egui::ViewportBuilder::default().with_inner_size([1280.0, 800.0])- .with_title("Ghidrust CodeBrowser"),+ .with_title(&title),..Default::default()};eframe::run_native(- "Ghidrust CodeBrowser",+ &title,opts,Box::new(|cc| Ok(Box::new(GhidrustApp::new(cc)))),)@@ -7953,8 +7954,10 @@ impl eframe::App for GhidrustApp {}ui.separator();if ui.button("About Ghidrust").clicked() {- self.status =- "Ghidrust — Rust RE foundation (Material 3 CodeBrowser shell)".into();+ self.status = format!(+ "Ghidrust {} — Rust RE toolkit (CodeBrowser shell)",+ env!("CARGO_PKG_VERSION")+ );self.log(self.status.clone());ui.close_menu();}diff --git a/skill/README.md b/skill/README.mdindex 163cdcb..fa8ccb7 100644--- a/skill/README.md+++ b/skill/README.md@@ -31,6 +31,8 @@ cargo run -p ghidrust-gui --releaseWindows: `.\target\release\ghidrust.exe` / `.\target\release\ghidrust-gui.exe`. Friction surfaces (`inventory`, `tree`, `artifact`, `process`, `rtti --filter`) match MCP tool names in `tool_defs()` — see [`SKILL.md`](SKILL.md).+Check build identity: `ghidrust --version` (same package version as MCP `server_info` and egui About). Live multi-step work needs MCP `tool_surface >= 2`; restart MCP after rebuild if `process_*` is missing.+MCP for agents (register in Cursor / Claude Desktop / other MCP clients — see root README):```bashdiff --git a/skill/SKILL.md b/skill/SKILL.mdindex bf6fac9..9267dde 100644--- a/skill/SKILL.md+++ b/skill/SKILL.md@@ -39,13 +39,15 @@ cargo build -p ghidrust-gui --release## Agent friction SOPs (required)+- **Version / stale MCP**: Call `server_info` first (or read `initialize.serverInfo`). This skill requires **`tool_surface >= 2`** (live process + artifacts + inventory). If `server_info` is missing, `tool_surface` is below that minimum, or `process_list` / `artifact_query` / `inventory` are absent from `tools/list` → rebuild `ghidrust`, point the MCP `command` at that binary, **restart the MCP server**. Do **not** conclude live process is unsupported; do **not** invent heap-scan scripts as a substitute. CLI/GUI/MCP share one package version (`ghidrust --version`, MCP `version`, egui About).- **Artifacts**: When envelope `entry_count` > preview or the host truncates tool text, drain via `artifact_query` / `artifact get` until `next_offset` is null. Never assume truncated MCP text is complete.- **Program identity**: Prefer `load` with absolute `path`, or `project` + `file_id`. Facts always include `resolved_path` or honest null — resolve before analyze/decompile.- **Inventory / tree**: Use `inventory <dir>` (PE VERSIONINFO + exe/dll) before OS `dir`/`Get-Item`. Use `tree` / `list_tree` for non-PE sidecars (existence/size only; no unpack).- **Address→function**: Always pass `addr` to `decompile` / `disassemble` / `gpu_decompile`; trust `resolved_entry` / `resolve` meta. Mid-body hits resolve to containing entry; unmapped → `no_containing_function` (no invented 1-insn fn).- **RTTI catalog**: Prefer `rtti_query` (`--filter`/`--exact`) before mangled `.?AV` string archaeology. Multi-vtable types report `vtable_vas[]` honestly.- **UTF-16 xrefs**: If `search_strings` returns `utf16le`, query `get_string_xrefs` with `encoding=all` (or `utf16le`) before concluding “no refs”.-- **Live process (Windows)**: `process_list` → `process_attach` → `process_modules` → `process_resolve` (`static_to_live`) → `process_read` → optional `process_regions` / `process_detach`. Bytes ≠ types. No write/breakpoints in MVP.+- **Live process (Windows)**: Multi-step live work **must** use MCP (or one long-lived process) — `process_list` → `process_attach` → `process_modules` → `process_resolve` (`static_to_live`) → `process_read` → optional `process_regions` / `process_detach`. Never chain separate CLI `ghidrust process` spawns expecting the same `session_id` (sessions are in-process). Bytes ≠ types. No write/breakpoints in MVP.+- **IL2CPP offline → live**: (1) `il2cpp_meta` / `il2cpp_map` for method RVAs (null = unknown offline). (2) `decompile` + `follow_stub` for resolve stubs with mapped slots. (3) On `runtime_unresolved` / `trampoline_or_invoker` (see `next_steps` in JSON) → live attach → `process_resolve(module, rva)` → `process_read` for class/instance bytes. `follow_stub` is **not** “get managed method body for every RVA.”- **Skill bootstrap**: GUI project open / Start writes `.grok/skills/ghidrust/SKILL.md` (disk or embedded fallback) and shows a fail-loud checklist (mcp/skill/agents/context + hash).- **Do not**: invent enum ordinals; treat `section_notes` as proof of hooks; read `.gdecomp` dumps as text (metrics JSON only).@@ -176,8 +178,11 @@ ghidrust project analyze PROJ_DIR --file ID \### MCP (`ghidrust mcp`)+Requires **`tool_surface >= 2`**. Check with `server_info` after connect.+| Tool | Args | Notes ||------|------|-------|+| `server_info` | — | Package `version`, `tool_surface`, features, live session_model || `load` | `path` **or** `project`+`file_id` | Map + `section_notes` + `resolved_path` || `disassemble` | `path`, optional `addr`, `count` | Containing-fn resolve + `decode_gaps` || `rtti` / `rtti_query` | `path`, optional `filter`/`exact`/`match` | Catalog; multi-vtable; artifact if large |@@ -198,7 +203,7 @@ ghidrust project analyze PROJ_DIR --file ID \| `il2cpp_stubs` | `binary`, optional `filter`, `max` | Resolve stubs (filter: name or C-string at `name_string_va`) || `il2cpp_icalls` | `binary`, optional `filter` | Engine name‖fn icall tables → index / RVA || `unity_inventory` | `path` | Player dir + PE VERSIONINFO helpers |-| `decompile` | `path`, optional `addr`, `count`, `stage`, **`follow_stub`** | Resolve meta + Stage-1 (expression fold, named calls); JSON: `folded_temps`, `token_count`, `goto_rate`; `runtime_unresolved` when IL2CPP slot empty |+| `decompile` | `path`, optional `addr`, `count`, `stage`, **`follow_stub`** | Resolve meta + Stage-1; JSON: `folded_temps`, `token_count`, `goto_rate`; `follow_stub` may be `runtime_unresolved` / `trampoline_or_invoker` with `next_steps` → live process || `list_gpu_strategies` | — | Strategy matrix || `gpu_decompile` | `path`, optional `addr`, `out` | VA resolve; metrics JSON; dump opaque || `rtti_gpu_bench` | `path` | CPU vs GPU RTTI |@@ -222,9 +227,10 @@ Canonical detail: [`docs/IL2CPP.md`](../docs/IL2CPP.md).| Raw bytes at VA | `ghidrust bytes PATH --addr HEX --count N --json` | `read_bytes` `{path, addr, count?}` || Xrefs (incl. data ptrs / skip stubs) | `ghidrust xrefs PATH --to HEX [--skip-stubs] [--classify]` | `get_xrefs_to` `{…, skip_stubs, classify}` || Decompile through stub | `ghidrust decompile GA.dll --addr HEX --follow-stub --json` | `decompile` `{…, follow_stub: true}` |+| Live resolve + read (runtime slots) | `ghidrust process …` (single spawn only) | MCP: attach → resolve → read (keep session) || Strings on metadata blob | `ghidrust strings META.dat --raw --match token --limit N` | `list_strings` `{path, raw:true, match, limit}` |-Wrong metadata magic → encrypted/obfuscated JSON with `next_steps` (fail closed). Never invent method or icall RVAs when pairing/map leaves them null.+Wrong metadata magic → encrypted/obfuscated JSON with `next_steps` (fail closed). Never invent method or icall RVAs when pairing/map leaves them null. Empty/runtime stub slots → `runtime_unresolved` + live `next_steps`; do not heap-scan as a substitute.**Engine icall recipe (generic):**@@ -245,6 +251,7 @@ Add `--json` for structured stdout.| Feature | Command ||---------|---------|| Help | `ghidrust help` |+| Version | `ghidrust version` / `--version` / `-V` `[--json]` (package + `tool_surface`) || Load | `ghidrust load <path\|--project DIR --file-id ID>` || Disasm | `ghidrust disasm <path> [--addr HEX] [--count N] [--skip-bad]` || Strings | `ghidrust strings <path> [--raw] [--encoding …] [--match MODE] [--limit N] [--out FILE] [--filter SUB]` |