openclaw - 💡(How to fix) Fix Expose BashSpawnHook to plugin SDK for spawn-time env contribution

Summary

Expose the existing BashSpawnHook mechanism to plugins so they can contribute env entries to bash-tool subprocess spawns through a contracted, filtered SDK path.

Problem to solve

BashSpawnHook and BashSpawnContext landed via #85341 (src/agents/sessions/tools/bash.ts:129-155) but no plugin can register a hook today: the agent's bash tool is constructed at src/agents/agent-tools.ts:674 via createCodingTools(codingRoot) with no options, so BashToolOptions.spawnHook is always undefined on the instance agents actually call.

Plugins needing to pass session-scoped values into subprocesses have no contracted seam and fall back to mutating process.env directly. That path is racy across concurrent turns (process.env is global), bypasses any safety filter, and leaves no audit trail.

Proposed solution

1. Narrow SDK subpath (e.g. openclaw/plugin-sdk/bash-spawn) exposing registerBashSpawnHook(fn).
2. Extend BashSpawnContext with optional sessionKey and runId so hooks can correlate against state populated by existing hooks (inbound_claim, subagent_spawned).
3. agent-tools.ts:674 constructs the bash tool with a composed hook: createCodingTools(codingRoot, { bash: { spawnHook: composed } }).
4. Composition is the single enforcement point — alphabetic key ordering for determinism, PATH override blocked, dangerous-env blacklist reusing isDangerousHostInheritedEnvVarName / isDangerousHostEnvOverrideVarName (src/infra/host-env-security.ts:108, 120). Plugin-side code cannot bypass.

Alternatives considered

• before_tool_call returning { params: { env: ... } } — does not reach spawn; bashSchema (bash.ts:25-30) only declares command and timeout, so the field is dropped.
• Rewriting params.command to prepend export FOO=bar; — works but is a string-level workaround the agent can disable (env -i, unset), and provides no security boundary.
• defineToolPlugin to register a replacement bash — abandons the upstream bash implementation.
• In-process process.env mutation — racy across concurrent turns and unfiltered.

Impact

• Affected: third-party and bundled plugins that need session-scoped subprocess identity propagation (channel routing, tenant identifiers, audit/trace context, etc.).
• Severity: blocks the seam — downstream forks have shipped host-side patches to add an analogous capability rather than wait.
• Frequency: every bash spawn in affected deployments.
• Consequence: forces patch-package / fork maintenance, or pushes plugins onto the unsafe process.env path.

Evidence/examples

• BashSpawnHook definition: src/agents/sessions/tools/bash.ts:129-155
• Bash construction without options: src/agents/agent-tools.ts:674
• Existing safety helpers to reuse at compose stage: src/infra/host-env-security.ts:108, 120
• Hooks already in SDK that complete the chain on plugin side: inbound_claim, subagent_spawned / _ended, session_end (src/plugins/hook-types.ts)

Additional information

Additive — existing spawnHook field on BashToolOptions and internal call sites stay unchanged; the proposed change only wires registered plugin hooks into the same field at the single construction site. No behavior change for callers that do not register a hook.

Happy to draft the PR (~30-50 LOC + test) once there's alignment on whether composeRegisteredHooks lives in the SDK subpath or in core glue, and whether BashSpawnContext extension with sessionKey / runId is acceptable.