WP Execute PHP

Last-resort power tool. Bypasses every safer layer (REST, wp-cli, introspect) to run arbitrary PHP in the WP request lifecycle. Five-layer safety chain. Audit-logged. Production-blocked unconditionally.

Iron Rule

When to use

• "Fire do_action('save_post', 42) and observe what happens" — runtime hook trigger.
• "Instantiate WC_Order(123) and dump its meta" — internal API call.
• "Set a transient programmatically for testing" — read/write the cache layer.
• "Run wp_schedule_event to register a cron" — internal scheduler call.
• Any case where REST/wp-cli/adapter does not expose the surface and a small PHP snippet is the cleanest fix.

Skip when:

• The work is post/option/user → wp-content.
• The work is a plugin's config → wp-edit-plugin.
• The work is "just look at state" → wp-introspect.
• The work is a wp-cli command → call wp_cli_run (companion's wp-cli endpoint via the same bridge, no need for execute-php).

Boundary

Owns:

• rolepod_wp_execute_php with the full safety chain.
• AST screen interpretation (Node side, mirrored on companion side).
• Production guard surfacing.
• Audit-id reporting to user.

Does not own:

• Any non-power workflow — those go to their own skill.
• wp-cli — even though wp-cli routes through companion now, that's wp_cli_run not execute_php.

Return / hand off:

• AST screen rejected the payload → go back to the user with the specific forbidden token; do not "work around" by encoding/obfuscation.
• Power profile not set → hand off to user: "set ROLEPOD_WPLAB_PROFILE=power env and reconnect."
• Site in guarded mode (FULL_ACCESS_REQUIRED / execute_php capability absent) → STOP and run the "Requesting Full Access" protocol below. The toggle is the owner's decision — never pressure, never proceed without it.

Requesting Full Access

When a task genuinely needs the power surface and the site is guarded, hand the user a decision, not an instruction. One message, four parts:

1. What + why — the exact task and why no guarded tool covers it (Iron Rule 1 already forced this answer).
2. The warning — plain words: "เปิดแล้ว AI จะควบคุมเว็บนี้ได้เต็มรูปแบบ — รัน PHP, แก้ไฟล์, สั่ง wp-cli แบบ destructive ได้ ถ้าเว็บนี้เป็นเว็บจริง ความผิดพลาดอาจทำให้เว็บล่ม" (match the user's language).
3. Backup first — offer rolepod_wp_backup_create BEFORE they flip the toggle; it works in guarded mode. Wait for it to finish (action=status) and confirm the backup id before proceeding.
4. The switch + the way back — where: wp-admin → Rolepod WP → Settings → AI Full Control → ON. And say up front that you will remind them to turn it back OFF when the task is done — then actually do that.

If the user declines: stop. Suggest the nearest guarded-mode alternative or manual steps they can run themselves. Declining is a valid outcome, not an obstacle to argue with.

Inputs to gather

• target_id.
• payload (the PHP snippet).
• confirm: true (mandatory).
• timeout_ms (default 5000).

Workflow

1. Justify the power tool

State why no safer skill solves this. If you cannot answer in one sentence → STOP, use the safer skill.

2. AST pre-screen mentally

Check the payload against references/ast-rules.md. If any forbidden token appears → STOP, rewrite without it.

3. Confirm preconditions

• ROLEPOD_WPLAB_PROFILE=power env present.
• Site is in Full Access mode (companion advertises execute_php). Guarded → run the "Requesting Full Access" protocol first.
• User explicitly OK'd confirm: true.

4. Run

rolepod_wp_execute_php { target_id, payload, confirm: true, timeout_ms? }. The call returns return_value, stdout, php_warnings, duration_ms, audit_id.

5. Surface

State the return_value, php_warnings count, duration, audit_id. The audit_id is the user's reference if anything went wrong server-side.

If a matching Rolepod agent is available

• rolepod:debug-issue for the broader debug context this fits into.
• rolepod:rolepod-builder for PHP-level investigation.

If no matching agent is available

1. Justify in one sentence why power tool.
2. Pre-screen payload against AST rules.
3. Confirm prereqs.
4. Run with confirm: true.
5. Surface result + audit_id.

Output

No durable artifact in the MCP. The companion writes an audit entry under wp-content/uploads/rolepod-wp-audit/<audit_id>.log (mode 0600) AND a row in wp_options.rolepod_wp_audit_log. The user owns the audit trail.

Examples

Read EVERY time before composing a new payload — the good/bad contrast catches the most common attack-surface mistakes:

• examples/php-examples.md — good vs bad payloads for a transient set + for a runtime hook dispatch.

References

Load when composing the FIRST payload of a session, or when the AST screen rejects something:

• references/ast-rules.md — the full forbidden-token list, the reason for each, the alternative if one exists.

Hard stops

• AST screen rejects (Node OR PHP side) → STOP, surface AST_REJECTED with the forbidden token; do not retry with obfuscation.
• POWER_PROFILE_REQUIRED → STOP, user must set env + reconnect.
• PRODUCTION_BLOCKED → STOP, no override.
• confirm: true missing → STOP, ask user.
• Payload size > 100 KB → STOP, refactor into smaller calls or use wp_cli_run for file-level ops.

Full Rolepod enhancement

Full Rolepod adds session-token-aware persistent eval (php_session endpoint) for multi-call scripts that share variables. Standalone, each execute-php call is independent.

Next phase

• Result is data → use it as input to the next skill (e.g. found IDs → wp-content to update).
• Result is a side effect (transient set, hook fired) → wp-health-check to confirm the system stayed healthy.
• Result is failure → wp-diagnose for the broader picture.