Activity Pluginization: Instrumentation Hooking, AMS Spoofing, and ActivityThread Subterfuge

The previous two articles deconstructed Android's class loading architecture (BaseDexClassLoader → DexPathList → dexElements) and resource management pipeline (Resources → AssetManager → resources.arsc). By reflectively manipulating these two conduits, pluginization frameworks empower the system to "find" classes and resources originating from external APKs. However, this is insufficient—Android's four major components (Activity, Service, BroadcastReceiver, ContentProvider) harbor a fundamental distinction from standard Java classes: They must be registered within the AndroidManifest.xml, otherwise the system categorically refuses to launch them.

A plugin APK is loaded dynamically at runtime; consequently, its Activities cannot be declared preemptively within the host's AndroidManifest.xml. How, then, do pluginization frameworks bypass this draconian system-level limitation to grant a completely unregistered "ghost" Activity a complete lifecycle?

The answer is embedded within every juncture of the Activity launch pipeline. The framework's core strategic doctrine is: "Deceive the heavens to cross the sea" during the outbound request, and execute a "bait-and-switch" during the inbound response.

Prerequisite: Comprehension of the Android ClassLoader hierarchy (Article 1) and Resource Loading mechanism (Article 2), alongside a foundational understanding of the Android OS Activity launch sequence.

The End-to-End Source Code Trace of Activity Launch

To master Hook mechanisms, one must first precisely map the end-to-end Activity launch pipeline. Only by understanding "what every step in the normal flow does" can one discern "where to surgically intervene, and why."

The Macro Flow: A Tri-Process Symphony

Launching a single Activity demands the orchestration of three distinct processes:

┌──────────────────────────────────────────────────────────────────┐
│                   App Process A (The Initiator)                  │
│                                                                  │
│  Activity.startActivity(intent)                                  │
│      ↓                                                           │
│  Instrumentation.execStartActivity()                             │
│      ↓ Binder IPC (Cross-Process Call)                           │
├──────────────────────────────────────────────────────────────────┤
│                   system_server Process                          │
│                                                                  │
│  ActivityTaskManagerService.startActivity()                      │
│      ↓                                                           │
│  ● Validate AndroidManifest.xml ← The roadblock for plugins      │
│  ● Parse Intent, resolve target Activity                         │
│  ● Manage Task and Back Stack                                    │
│  ● If target process is offline, request Zygote to fork it       │
│      ↓ Binder IPC (Callback to Target Process)                   │
├──────────────────────────────────────────────────────────────────┤
│                   App Process B (The Target)                     │
│                                                                  │
│  ApplicationThread.scheduleTransaction()                         │
│      ↓ Switch to Main Thread via Handler(H)                      │
│  ActivityThread.handleLaunchActivity()                           │
│      ↓                                                           │
│  ActivityThread.performLaunchActivity()                          │
│      ├─ Instrumentation.newActivity() ← Reflectively creates instance│
│      ├─ Activity.attach()             ← Binds Context, Window    │
│      └─ Instrumentation.callActivityOnCreate() ← Triggers onCreate│
└──────────────────────────────────────────────────────────────────┘

Think of launching an Activity like sending a courier package. The initiating App is the sender; AMS (ActivityManagerService) within system_server is the dispatch center; the target App process is the recipient. The dispatch center inspects if the "package is legal" (Manifest validation), routes it (Task stack management), and notifies the recipient to sign for it (Instantiate Activity).

The Initiator: From startActivity to Instrumentation

When a developer invokes startActivity(intent), it internally traverses the following call chain:

// Activity.java (AOSP Source, simplified)
@Override
public void startActivity(Intent intent) {
    startActivity(intent, null);
}

@Override
public void startActivity(Intent intent, @Nullable Bundle options) {
    // ...
    startActivityForResult(intent, -1, options);
}

public void startActivityForResult(Intent intent, int requestCode,
        @Nullable Bundle options) {
    // ...
    // CRITICAL: Delegation to Instrumentation
    Instrumentation.ActivityResult ar =
        mInstrumentation.execStartActivity(
            this,                    // Current Activity
            mMainThread.getApplicationThread(), // App's Binder proxy
            mToken,                  // Activity's identity Token
            this,                    // Activity waiting for result
            intent,                  // Launch Intent
            requestCode,             // Request Code
            options);                // Additional Options
    // ...
}

Pay close attention to the mInstrumentation member variable. Every ActivityThread (the master orchestrator of the app's main thread) possesses exactly one Instrumentation instance, shared across all Activities. Instrumentation operates as the "Grand Vizier" of Activity lifecycle management:

// Instrumentation.java (AOSP Source, key method)
public ActivityResult execStartActivity(
        Context who, IBinder contextThread, IBinder token,
        Activity target, Intent intent, int requestCode,
        Bundle options) {

    // ... Notify Activity monitors (utilized by testing frameworks)

    // CORE: Invoke AMS/ATMS startActivity via Binder
    int result = ActivityTaskManager.getService().startActivity(
            whoThread,              // IApplicationThread Binder proxy
            who.getOpPackageName(), // Caller package name
            who.getAttributionTag(),
            intent,                 // Launch Intent
            intent.resolveTypeIfNeeded(who.getContentResolver()),
            token,                  // Caller Activity Token
            target != null ? target.mEmbeddedID : null,
            requestCode,
            0,                      // Launch flags
            null,                   // ProfilerInfo
            options);               // ActivityOptions

    // Inspect launch result; throws Exception upon failure
    checkStartActivityResult(result, intent);
    return null;
}

ActivityTaskManager.getService() yields an IActivityTaskManager Binder proxy object—an AIDL interface whose startActivity invocation triggers Inter-Process Communication (IPC), dispatching the request to the ActivityTaskManagerService (ATMS) residing within the system_server process.

AMS/ATMS: Manifest Validation — The Pluginization Blockade

Upon receiving the request, ATMS within system_server executes a battery of validations. The most lethal validation for pluginization is the Manifest Validation:

// ActivityTaskManagerService.java (AOSP Source, simplified chain)
// startActivity → startActivityAsUser → ... → ActivityStarter.execute()

// ActivityStarter.java
private int executeRequest(Request request) {
    // ...

    // Parse Intent to lookup target Activity metadata
    ResolveInfo rInfo = getSupervisor().resolveIntent(intent, ...);
    ActivityInfo aInfo = getSupervisor().resolveActivity(intent, rInfo, ...);

    // CRITICAL VALIDATION: If aInfo is null, the target Activity is NOT registered
    // in the Manifest of ANY installed APK — ERROR!
    if (aInfo == null) {
        // This is exactly where Plugin Activities are rejected!
        // Will ultimately result in an ActivityNotFoundException.
        return START_INTENT_NOT_RESOLVED;
    }

    // Permission checks, Task stack management, etc...
}

This is the fundamental paradox of Plugin Activities: The plugin APK is loaded dynamically; it is absent from the system's registry of installed applications. Consequently, plugin Activities structurally cannot pass the Manifest validation. Executing startActivity targeting a plugin Activity directly will exclusively yield an ActivityNotFoundException.

The Recipient: How ActivityThread Instantiates the Activity

Once AMS passes validation, it fires a Binder callback to the target process's ApplicationThread. Since Android 9 (API 28), the system transitioned to the ClientTransaction architecture, deprecating the legacy LAUNCH_ACTIVITY message mechanism:

Android 8 and older (Legacy Architecture):
  AMS → ApplicationThread.scheduleLaunchActivity()
      → H.sendMessage(LAUNCH_ACTIVITY, record)
      → handleLaunchActivity()

Android 9 and newer (ClientTransaction Architecture):
  AMS → ClientLifecycleManager.scheduleTransaction()
      → ApplicationThread.scheduleTransaction(ClientTransaction)
      → TransactionExecutor.execute()
          ├─ executeCallbacks() → LaunchActivityItem.execute()
          └─ executeLifecycleState() → ResumeActivityItem.execute()

Regardless of the architecture, the terminus is ActivityThread.performLaunchActivity()—the absolute core method for Activity instantiation:

// ActivityThread.performLaunchActivity() (AOSP Source, simplified)
private Activity performLaunchActivity(ActivityClientRecord r,
        Intent customIntent) {

    // 1. Acquire component metadata
    ComponentName component = r.intent.getComponent();

    // 2. Reflectively instantiate the Activity via Instrumentation
    //    The ClassLoader deployed here is r.packageInfo.getClassLoader()
    //    i.e., the Application's PathClassLoader
    Activity activity = mInstrumentation.newActivity(
            cl,                         // ClassLoader
            component.getClassName(),   // Activity Class Name (FQN)
            r.intent);                  // Intent

    // 3. Instantiate Application (if not already instantiated)
    Application app = r.packageInfo.makeApplicationInner(false, mInstrumentation);

    // 4. Instantiate and bind Context
    ContextImpl appContext = createBaseContextForActivity(r);
    activity.attach(appContext, this, getInstrumentation(),
            r.token, r.ident, app, r.intent, r.activityInfo,
            title, r.parent, r.embeddedID, r.lastNonConfigurationInstances,
            config, r.referrer, r.voiceInteractor, window, ...);

    // 5. Trigger onCreate lifecycle
    if (r.isPersistable()) {
        mInstrumentation.callActivityOnCreate(activity, r.state,
                r.persistentState);
    } else {
        mInstrumentation.callActivityOnCreate(activity, r.state);
    }

    return activity;
}

The implementation of Instrumentation.newActivity() is brutally straightforward—it is purely reflective object creation:

// Instrumentation.java (AOSP Source)
public Activity newActivity(ClassLoader cl, String className, Intent intent)
        throws InstantiationException, IllegalAccessException,
        ClassNotFoundException {
    String pkg = intent != null && intent.getComponent() != null
            ? intent.getComponent().getPackageName() : null;
    return getFactory(pkg).instantiateActivity(cl, className, intent);
}

// AppComponentFactory.java (Default implementation)
public @NonNull Activity instantiateActivity(@NonNull ClassLoader cl,
        @NonNull String className, @Nullable Intent intent)
        throws InstantiationException, IllegalAccessException,
        ClassNotFoundException {
    return (Activity) cl.loadClass(className).newInstance();
}

Critical Discovery: The Activity class name is directly extracted from r.intent.getComponent().getClassName(), and r.intent is fed directly back from AMS. If we can alter the class name embedded within this Intent after the AMS callback but before newActivity is invoked, we can force the system to instantiate our desired Plugin Activity!

The Core Paradox and the Grand Strategy

The Essence of the Paradox

Distilling the aforementioned analysis into a single axiom: AMS validates the Manifest within the highly privileged system_server process; the application layer possesses zero authority to mutate system_server behavior.

However, pivoting the perspective—AMS solely validates the Activity metadata embedded within the Intent, and the initial construction of that Intent occurs within the application process. If we can "tamper" with the Intent before it exits the application boundary, and "restore the crime scene" upon the AMS callback, we can flawlessly bypass the validation.

The "Spoofing and Subterfuge" Strategy

                    ┌── Application Process ──┐
                    │                         │
startActivity       │  Hook Point 1           │
(PluginActivity)──→ │  ● Mutate the Intent's  │
                    │    target from          │
                    │    "PluginActivity"     │
                    │    to                   │  ──→ AMS Validation Passed!
                    │    "StubActivity"       │      (StubActivity is legally
                    │    (Placeholder)        │       registered in Manifest)
                    │                         │
                    │  Hook Point 2           │
            AMS ──→ │  ● Mutate the Intent's  │
         Callback   │    target from          │
                    │    "StubActivity"       │
                    │    back to              │  ──→ The ACTUAL Plugin Activity
                    │    "PluginActivity"     │      is instantiated!
                    │                         │
                    └─────────────────────────┘

This is the definitive architecture for Activity Pluginization:

1. Hook Point 1 (Outbound Spoofing): Prior to dispatching the startActivity request to AMS, replace the target Activity within the Intent with a "Stub Activity" (placeholder) that has been preemptively registered in the host's Manifest. AMS audits a perfectly legal, registered Activity and approves the launch.
2. Hook Point 2 (Inbound Subterfuge): Prior to the ActivityThread instantiating the Activity upon AMS callback, extract the Intent and revert the target from the "Stub Activity" back to the genuine Plugin Activity. Instrumentation.newActivity() proceeds to execute reflection using the plugin's ClassLoader, thereby birthing the Plugin Activity.

Next, we will dissect the specific technical implementations of these two Hook points.

The Stub Activity: Securing a Manifest "Placeholder"

Before executing the Hooks, a fleet of "Stub Activities" must be preemptively declared within the host's AndroidManifest.xml. These Stub Activities harbor zero business logic; their sole existential purpose is to escort the Plugin Activity securely past the AMS Manifest validation.

Why do we need Multiple Stubs?

Activities govern task stacks via four distinct launchMode paradigms. AMS strictly enforces these paradigms during the launch request by reading the launchMode declared in the Manifest. Therefore, distinct Stubs must be reserved for every conceivable mode:

<!-- Placeholder declarations within Host AndroidManifest.xml -->

<!-- standard mode: Generates a new instance per launch -->
<activity android:name=".stub.StubActivity$Standard1"
    android:launchMode="standard" />
<activity android:name=".stub.StubActivity$Standard2"
    android:launchMode="standard" />
<!-- Multiple declarations are necessary if launching multiple standard Activities concurrently -->

<!-- singleTop mode: Top-of-stack reuse -->
<activity android:name=".stub.StubActivity$SingleTop1"
    android:launchMode="singleTop" />

<!-- singleTask mode: In-stack reuse -->
<activity android:name=".stub.StubActivity$SingleTask1"
    android:launchMode="singleTask" />

<!-- singleInstance mode: Exclusive task stack -->
<activity android:name=".stub.StubActivity$SingleInstance1"
    android:launchMode="singleInstance" />

<!-- Stubs demanding specific themes (Transparent, Dialog, etc.) must also be declared -->
<activity android:name=".stub.StubActivity$Transparent1"
    android:launchMode="standard"
    android:theme="@android:style/Theme.Translucent" />

<!-- Stubs allocated to isolated processes (for multi-process plugin architecture) -->
<activity android:name=".stub.StubActivity$Process1"
    android:launchMode="standard"
    android:process=":plugin1" />

Think of this as a hotel permanently reserving various room layouts—Standard, Suite, Presidential—ensuring that regardless of what "type of guest" (Plugin Activity) arrives, a legally registered room configuration perfectly matches their requirements.

Hook Architecture 1: Instrumentation Replacement

The Principle

Instrumentation serves as the "Grand Vizier" of Activity lifecycles. ActivityThread maintains an mInstrumentation field; every Activity launch (execStartActivity) and instantiation (newActivity) bottlenecks through it.

If we forcefully replace the system's default Instrumentation with a custom subclass proxy, we can intercept both the "outbound" and "inbound" vectors simultaneously—executing both "AMS Spoofing" and "Plugin Restoration" within a solitary, highly cohesive object.

ActivityThread
    │
    ├── mInstrumentation (Original)
    │       ↓ Replaced By
    ├── mInstrumentation (Custom ProxyInstrumentation)
    │       ├── execStartActivity()  → Hook Point 1: Intent Spoofing
    │       └── newActivity()        → Hook Point 2: Intent Restoration & Instantiation

Step 1: Reflective Replacement of Instrumentation

/**
 * Hijacks and replaces the Instrumentation instance within ActivityThread.
 * This is the genesis of the entire Hook chain.
 */
public static void hookInstrumentation() throws Exception {
    // Acquire the ActivityThread singleton (currentActivityThread)
    Class<?> activityThreadClass = Class.forName("android.app.ActivityThread");
    Method currentActivityThreadMethod = activityThreadClass
            .getDeclaredMethod("currentActivityThread");
    currentActivityThreadMethod.setAccessible(true);
    Object activityThread = currentActivityThreadMethod.invoke(null);

    // Extract the original Instrumentation instance
    Field instrumentationField = activityThreadClass
            .getDeclaredField("mInstrumentation");
    instrumentationField.setAccessible(true);
    Instrumentation originalInstrumentation =
            (Instrumentation) instrumentationField.get(activityThread);

    // Substitute with our custom Proxy Instrumentation
    ProxyInstrumentation proxy = new ProxyInstrumentation(
            originalInstrumentation);
    instrumentationField.set(activityThread, proxy);

    Log.d("PluginHook", "Instrumentation hijacked successfully");
}

Step 2: Implementation of ProxyInstrumentation

/**
 * Custom Instrumentation Proxy.
 * Intercepts Activity launch and instantiation to architect plugin payload delivery.
 */
public class ProxyInstrumentation extends Instrumentation {

    // The original Instrumentation, utilized for delegating non-plugin calls
    private final Instrumentation mOriginal;

    // Extra Key designated for smuggling the true Plugin Intent
    private static final String EXTRA_REAL_INTENT = "plugin_real_intent";

    // FQN of the predefined Stub Activity
    private static final String STUB_ACTIVITY =
            "com.host.stub.StubActivity$Standard1";

    public ProxyInstrumentation(Instrumentation original) {
        this.mOriginal = original;
    }

    /**
     * Hook Point 1: Intercept startActivity requests
     * Spoofs the target component to a Stub Activity prior to AMS transmission
     */
    public ActivityResult execStartActivity(
            Context who, IBinder contextThread, IBinder token,
            Activity target, Intent intent, int requestCode,
            Bundle options) {

        // Determine if this Intent targets a Plugin Activity
        if (isPluginIntent(intent)) {
            Log.d("PluginHook", "Intercepting Plugin Activity launch: "
                    + intent.getComponent());

            // Smuggle the genuine Intent payload (Plugin Activity component)
            intent.putExtra(EXTRA_REAL_INTENT, intent.getComponent().clone());

            // Spoof the Intent target to the legal Stub Activity
            // AMS will solely perceive this registered placeholder.
            intent.setComponent(new ComponentName(
                    who.getPackageName(), STUB_ACTIVITY));
        }

        // Delegate execution via reflection to the original Instrumentation.
        // execStartActivity is hidden (@hide), demanding reflection.
        try {
            Method execMethod = Instrumentation.class.getDeclaredMethod(
                    "execStartActivity",
                    Context.class, IBinder.class, IBinder.class,
                    Activity.class, Intent.class, int.class, Bundle.class);
            execMethod.setAccessible(true);
            return (ActivityResult) execMethod.invoke(
                    mOriginal, who, contextThread, token,
                    target, intent, requestCode, options);
        } catch (Exception e) {
            throw new RuntimeException("execStartActivity reflection failed", e);
        }
    }

    /**
     * Hook Point 2: Intercept Activity Instantiation
     * Reverts the Stub Activity back to the genuine Plugin Activity post-AMS callback
     */
    @Override
    public Activity newActivity(ClassLoader cl, String className,
            Intent intent) throws InstantiationException,
            IllegalAccessException, ClassNotFoundException {

        // Probe the Intent for smuggled genuine Activity metadata
        ComponentName realComponent = intent.getParcelableExtra(
                EXTRA_REAL_INTENT);

        if (realComponent != null) {
            Log.d("PluginHook", "Restoring Plugin Activity: " + realComponent);

            // Acquire the dedicated Plugin ClassLoader
            String pluginClassName = realComponent.getClassName();
            ClassLoader pluginClassLoader = PluginManager.getInstance()
                    .getPluginClassLoader(realComponent.getPackageName());

            // Force instantiation utilizing the Plugin ClassLoader instead of the Host's
            return super.newActivity(pluginClassLoader,
                    pluginClassName, intent);
        }

        // Non-plugin Activity; proceed via standard pipeline
        return super.newActivity(cl, className, intent);
    }

    @Override
    public void callActivityOnCreate(Activity activity,
            Bundle icicle) {
        // Prime location for executing pre-onCreate payload injections.
        // E.g., Injecting Plugin Resources, Context substitution, etc.
        injectPluginResourcesIfNeeded(activity);
        mOriginal.callActivityOnCreate(activity, icicle);
    }

    /**
     * Identifies whether the Intent targets a Plugin Activity
     */
    private boolean isPluginIntent(Intent intent) {
        ComponentName component = intent.getComponent();
        if (component == null) return false;
        return PluginManager.getInstance()
                .isPluginActivity(component.getClassName());
    }

    /**
     * Injects the dedicated Plugin Resources into the Plugin Activity
     */
    private void injectPluginResourcesIfNeeded(Activity activity) {
        // Leverages the Resource Loading paradigms discussed in the previous article
        // Swaps the Activity's mResources reference to the Plugin Resources
    }
}

The Architectural Advantage of Instrumentation Hooking

The paramount supremacy of this architecture is resolving dual vectors through a singular Hook point. Both execStartActivity and newActivity reside within the cohesive Instrumentation instance, yielding high code cohesion and lucid logic. This is the exact architecture deployed by the VirtualAPK framework.

Hook Architecture 2: Dynamic AMS Proxy + Handler Callback

An alternative, historically classical architecture mandates hooking two distinct, geographically separated points: deploying a Dynamic Proxy to intercept the AMS Binder interface (outbound spoofing), and configuring a Handler Callback to intercept ActivityThread.mH (inbound subterfuge).

Outbound Hook: Dynamically Proxying IActivityManager / IActivityTaskManager

ActivityTaskManager.getService() yields a Binder proxy adhering to the IActivityTaskManager interface. Internally, this proxy is cached as a singleton. By wrapping this singleton in a Java Dynamic Proxy, we can unconditionally intercept all cross-process dispatches targeting AMS.

/**
 * Hooks the AMS Binder proxy to intercept startActivity invocations.
 * Implements compatibility shims bridging Android 10+ ATMS and legacy AMS.
 */
public static void hookAMSBinder() throws Exception {
    Object amsProxy;

    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        // Android 10+: Hook IActivityTaskManager
        // ActivityTaskManager maintains an IActivityTaskManagerSingleton
        Class<?> atmClass = Class.forName("android.app.ActivityTaskManager");
        Field singletonField = atmClass.getDeclaredField(
                "IActivityTaskManagerSingleton");
        singletonField.setAccessible(true);
        Object singleton = singletonField.get(null);

        // The mInstance field within the Singleton class holds the true Binder proxy
        Class<?> singletonClass = Class.forName("android.util.Singleton");
        Field instanceField = singletonClass.getDeclaredField("mInstance");
        instanceField.setAccessible(true);
        Object originalProxy = instanceField.get(singleton);

        // Generate the Dynamic Proxy
        Class<?> iATMInterface = Class.forName(
                "android.app.IActivityTaskManager");
        Object hookedProxy = Proxy.newProxyInstance(
            iATMInterface.getClassLoader(),
            new Class[]{iATMInterface},
            new AMSInvocationHandler(originalProxy));

        // Overwrite the singleton's Binder proxy with our Dynamic Proxy
        instanceField.set(singleton, hookedProxy);

    } else {
        // Android 8~9: Hook IActivityManager
        Class<?> amClass = Class.forName("android.app.ActivityManager");
        Field singletonField = amClass.getDeclaredField(
                "IActivityManagerSingleton");
        singletonField.setAccessible(true);
        Object singleton = singletonField.get(null);

        Class<?> singletonClass = Class.forName("android.util.Singleton");
        Field instanceField = singletonClass.getDeclaredField("mInstance");
        instanceField.setAccessible(true);
        Object originalProxy = instanceField.get(singleton);

        Class<?> iAMInterface = Class.forName(
                "android.app.IActivityManager");
        Object hookedProxy = Proxy.newProxyInstance(
            iAMInterface.getClassLoader(),
            new Class[]{iAMInterface},
            new AMSInvocationHandler(originalProxy));

        instanceField.set(singleton, hookedProxy);
    }
}

/**
 * InvocationHandler governing the AMS Binder Proxy.
 * Intercepts startActivity to spoof the Intent's component target.
 */
static class AMSInvocationHandler implements InvocationHandler {
    private final Object mOriginal;

    AMSInvocationHandler(Object original) {
        this.mOriginal = original;
    }

    @Override
    public Object invoke(Object proxy, Method method, Object[] args)
            throws Throwable {

        // Exclusively intercept the 'startActivity' method
        if ("startActivity".equals(method.getName())) {
            // Scan argument list to locate the Intent object
            int intentIndex = -1;
            for (int i = 0; i < args.length; i++) {
                if (args[i] instanceof Intent) {
                    intentIndex = i;
                    break;
                }
            }

            if (intentIndex >= 0) {
                Intent originalIntent = (Intent) args[intentIndex];

                // Determine if Intent targets a Plugin Activity
                if (isPluginIntent(originalIntent)) {
                    // Smuggle genuine target metadata
                    originalIntent.putExtra("plugin_real_component",
                            originalIntent.getComponent());

                    // Execute Spoof: Overwrite target with Stub Activity
                    originalIntent.setComponent(new ComponentName(
                            "com.host.app",
                            "com.host.stub.StubActivity$Standard1"));
                }
            }
        }

        // Pass execution to the original proxy method
        return method.invoke(mOriginal, args);
    }
}

Inbound Hook: Intercepting ActivityThread.mH

Post-AMS callback, legacy architectures routed the dispatch through ActivityThread's internal Handler (mH) by issuing a LAUNCH_ACTIVITY message. By injecting a custom mCallback into this Handler, we can ruthlessly intercept the message mere nanoseconds before handleMessage processes it:

/**
 * Hooks ActivityThread's mH Handler.
 * Restores the spoofed Intent immediately prior to Activity instantiation.
 */
public static void hookHandler() throws Exception {
    // Acquire ActivityThread singleton
    Class<?> atClass = Class.forName("android.app.ActivityThread");
    Method currentMethod = atClass.getDeclaredMethod("currentActivityThread");
    currentMethod.setAccessible(true);
    Object activityThread = currentMethod.invoke(null);

    // Acquire mH (The Main Thread Handler)
    Field mHField = atClass.getDeclaredField("mH");
    mHField.setAccessible(true);
    Handler mH = (Handler) mHField.get(activityThread);

    // Inject Callback. Handler execution hierarchy dictates:
    // mCallback.handleMessage() executes BEFORE Handler.handleMessage()
    // Returning 'true' from mCallback aborts Handler.handleMessage() execution.
    Field callbackField = Handler.class.getDeclaredField("mCallback");
    callbackField.setAccessible(true);
    callbackField.set(mH, new HookCallback(mH));
}

/**
 * Custom Handler.Callback.
 * Intercepts LAUNCH_ACTIVITY (or EXECUTE_TRANSACTION) messages to restore the Plugin Intent.
 */
static class HookCallback implements Handler.Callback {
    private final Handler mOriginalHandler;

    // LAUNCH_ACTIVITY constant (Pre-Android 9)
    private static final int LAUNCH_ACTIVITY = 100;
    // EXECUTE_TRANSACTION constant (Android 9+)
    private static final int EXECUTE_TRANSACTION = 159;

    HookCallback(Handler handler) {
        this.mOriginalHandler = handler;
    }

    @Override
    public boolean handleMessage(@NonNull Message msg) {
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.P) {
            // Android 8 and older: Direct LAUNCH_ACTIVITY payload
            if (msg.what == LAUNCH_ACTIVITY) {
                handleLaunchActivity(msg);
            }
        } else {
            // Android 9+: ClientTransaction payload
            // Mandates deep extraction of the LaunchActivityItem
            if (msg.what == EXECUTE_TRANSACTION) {
                handleExecuteTransaction(msg);
            }
        }

        // Yield false to permit the original Handler to finalize processing
        return false;
    }

    /**
     * Legacy Architecture (Android 8 and older):
     * msg.obj is ActivityClientRecord; mutate its 'intent' field directly.
     */
    private void handleLaunchActivity(Message msg) {
        try {
            Object record = msg.obj; // ActivityClientRecord
            Field intentField = record.getClass().getDeclaredField("intent");
            intentField.setAccessible(true);
            Intent intent = (Intent) intentField.get(record);

            // Execute Subterfuge: Restore the genuine Plugin Activity metadata
            restorePluginIntent(intent);
        } catch (Exception e) {
            Log.e("PluginHook", "Intent restoration failed", e);
        }
    }

    /**
     * Modern Architecture (Android 9+):
     * msg.obj is a ClientTransaction; mandates extraction of LaunchActivityItem.
     */
    private void handleExecuteTransaction(Message msg) {
        try {
            Object transaction = msg.obj; // ClientTransaction
            Field callbacksField = transaction.getClass()
                    .getDeclaredField("mActivityCallbacks");
            callbacksField.setAccessible(true);
            List<?> callbacks = (List<?>) callbacksField.get(transaction);

            if (callbacks == null || callbacks.isEmpty()) return;

            for (Object item : callbacks) {
                // Isolate the LaunchActivityItem
                if (item.getClass().getName().contains("LaunchActivityItem")) {
                    Field intentField = item.getClass()
                            .getDeclaredField("mIntent");
                    intentField.setAccessible(true);
                    Intent intent = (Intent) intentField.get(item);

                    restorePluginIntent(intent);
                }
            }
        } catch (Exception e) {
            Log.e("PluginHook", "ClientTransaction Intent restoration failed", e);
        }
    }

    /**
     * Extracts the genuine Plugin component from the Intent Extras and overwrites the target.
     */
    private void restorePluginIntent(Intent intent) {
        if (intent == null) return;
        ComponentName realComponent = intent.getParcelableExtra(
                "plugin_real_component");
        if (realComponent != null) {
            intent.setComponent(realComponent);
            Log.d("PluginHook", "Plugin Activity Restored: " + realComponent);
        }
    }
}

Architectural Comparison of Hooking Strategies

Lifecycle Governance: The Stub "Lives", the Plugin "Thrives"

Through the aforementioned Hook stratagems, the Plugin Activity successfully achieves instantiation. Yet, a glaring question remains: Will its lifecycle callbacks (onStart, onResume, onPause, onStop, onDestroy) execute correctly?

The unequivocal answer is: Yes—and it requires absolutely zero additional Hooking.

Why do Lifecycles Auto-Resolve?

This is dictated by how AMS physically tracks Activities. AMS governs state via an internal ActivityRecord structure. The definitive identity token for an ActivityRecord is an IBinder token.

AMS Perspective:                        App Process Perspective:
┌─────────────────────┐                 ┌─────────────────────┐
│ ActivityRecord      │                 │ Activity Instance   │
│   token: 0xABC      │ ←── Maps To ──→ │   mToken: 0xABC     │
│   component:        │                 │   Actual Type:      │
│   StubActivity      │                 │   PluginActivity    │
│   (Stub Name)       │                 │   (Plugin Class)    │
└─────────────────────┘                 └─────────────────────┘

AMS rigidly registers the component as the "Stub Activity", completely oblivious to the fact that the actual instance running in the app process is a drastically different class. AMS exclusively uses the token for scheduling. When AMS demands an onResume trigger, it fires the callback targeting the token. The application process routes this token to the mapped Activity instance (the PluginActivity) and blindly triggers the lifecycle method.

Therefore, as long as the token is bound correctly (executed natively within Activity.attach()), the Plugin Activity will automatically, flawlessly receive all lifecycle dispatches.

Edge Cases Demanding Framework Intervention

While baseline lifecycles auto-resolve, the framework must engineer polyfills for specific architectural edge cases:

Activity Hooking Strategies Across Mainstream Frameworks

VirtualAPK (DiDi): Total Instrumentation Hijacking

VirtualAPK executes Strategy 1—wholesale replacement of Instrumentation. Its core engine, VAInstrumentation, governs both the outbound spoofing and inbound restoration, subsequently injecting the Plugin's Resources and ClassLoader during callActivityOnCreate.

VirtualAPK Activity Launch Pipeline:
1. Hijack ActivityThread.mInstrumentation → VAInstrumentation
2. On startActivity, VAInstrumentation.execStartActivity():
   ● Lookup matching Stub for the target Activity (based on launchMode)
   ● Overwrite Intent target to Stub
3. AMS validation passes, returns callback for Activity creation
4. VAInstrumentation.newActivity():
   ● Extract genuine Activity FQN from Intent Extra
   ● Load and instantiate via Plugin ClassLoader
5. VAInstrumentation.callActivityOnCreate():
   ● Inject Plugin Resources
   ● Trigger onCreate

Shadow (Tencent): Zero-Reflection Proxy Activity

Shadow's foundational philosophy is the absolute eradication of Framework-level private API reflection. It blatantly refuses to Hook Instrumentation or the AMS Binder. Instead, it pioneers a radically divergent architecture: The Proxy Activity Paradigm.

Traditional Hook Paradigms:                  Shadow Proxy Paradigm:

startActivity                                startActivity
    ↓                                            ↓
Hook Instrumentation                         Directly Launch PluginContainerActivity
(Spoof Intent)                               (Legally Registered in Manifest)
    ↓                                            ↓
AMS Validation Passed                        AMS Validation Passed
    ↓                                            ↓
Hook newActivity                             PluginContainerActivity.onCreate():
(Restore Intent, Instantiate Plugin)         ● Extract Plugin Activity FQN from Intent
    ↓                                        ● Instantiate ShadowActivity via Plugin ClassLoader
Plugin Activity Instance                     ● Manually forward ALL lifecycle callbacks to ShadowActivity

Shadow's supreme technique relies on Compile-Time Bytecode Transformation:

1. Transform Phase: During plugin compilation, Shadow's custom Gradle plugin ruthlessly rewrites the inheritance chain of all Plugin Activities, swapping their superclass from Activity / AppCompatActivity to ShadowActivity (A custom base class supplied by the Shadow framework).
2. ShadowActivity maintains a HostActivityDelegator interface, serving as the communication bridge to the host container. All Context-bound methods (getResources(), getAssets(), etc.) are hard-delegated through this interface to the host container.
3. PluginContainerActivity is fully registered in the Host Manifest; it is a hyper-minimalist shell. Upon launch, it instantiates the corresponding ShadowActivity and systematically forwards every single lifecycle callback directly into it.

┌──────────────────────────────────────────────┐
│ PluginContainerActivity (Host Shell)         │
│  ■ Fully Registered in Manifest              │
│  ■ Maintains ShadowActivity instance         │
│  ■ Forwards all lifecycle dispatches         │
│                                              │
│  onCreate()  → delegate.onCreate()           │
│  onResume()  → delegate.onResume()           │
│  onPause()   → delegate.onPause()            │
│  onDestroy() → delegate.onDestroy()          │
└──────────────────────────────────────────────┘
         ↕ Lifecycle Forwarding
┌──────────────────────────────────────────────┐
│ ShadowActivity (Plugin Business Logic)       │
│  ■ Superclass overwritten at compile-time    │
│  ■ Context methods delegated to Container    │
│  ■ Developer codes as standard Activity      │
└──────────────────────────────────────────────┘

Framework Comparison Matrix

The Devastating Impact of Android OS Evolution on Activity Hooking

Evaluating the historical trajectory, Google is systematically sealing access to internal Framework APIs with extreme prejudice. Operations like reflectively overwriting mInstrumentation, dynamically proxying AMS singletons, or tampering with mH.mCallback are fundamentally reliant on Hidden APIs. The Greylist mechanics introduced in Android 9 formally classified these actions as "deprecated," and any future OS iteration threatens to execute them via the Blacklist.

This existential threat validates Shadow's "Zero-Reflection" doctrine—by executing compile-time bytecode transformation coupled with legally sanctioned runtime proxy forwarding, it fundamentally circumvents Hidden API limitations, achieving the absolute pinnacle of system compatibility and long-term stability.

Activity Pluginization stands as the most architecturally complex domain within the entire pluginization technology stack. It mandates profound mastery over the cross-process Activity launch pipeline, demanding surgical interception and restoration at both the "outbound" and "inbound" perimeters.

The foundational paradigm is crystallized in three phases: Placeholder Declaration (Manifest pre-registration) → Outbound Spoofing (Intent targeting Stub) → Inbound Subterfuge (Restoring the Plugin Activity). Distinct frameworks leverage divergent architectural trade-offs to execute this—VirtualAPK engineered the cohesive "Instrumentation Replacement" strategy, DroidPlugin championed the decoupled "AMS Proxy + Handler Hook," while Shadow abandoned the paradigm entirely for the revolutionary "Zero-Reflection Proxy."

The subsequent article will conduct a comprehensive, horizontal evaluation of these mainstream pluginization frameworks (VirtualAPK, RePlugin, Shadow, Atlas), comparing them across architectural design, API stability, performance overhead, and deployment suitability to guide your technical infrastructure decisions.