Skip to content

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.md
index 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 artifacts
diff --git a/crates/ghidrust-cli/src/main.rs b/crates/ghidrust-cli/src/main.rs
index 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(&params) {
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.rs
index 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.rs
index 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.md
index 163cdcb..fa8ccb7 100644
--- a/skill/README.md
+++ b/skill/README.md
@@ -31,6 +31,8 @@ cargo run -p ghidrust-gui --release
Windows: `.\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):
```bash
diff --git a/skill/SKILL.md b/skill/SKILL.md
index 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]` |