[Feature]: optional seam to surface external containment verdicts as agent observations

Is there an existing feature request for this?

• I have searched existing issues and feature requests, and this is not a duplicate.

Problem or Use Case

Not a bug, and not asking the team to build or maintain a sandbox. I run the OpenHands CLI (1.16.0 / SDK 1.21.0) inside an external Linux containment layer and hit one real UX gap I think the SDK is the right place to solve.

When the agent runs inside kernel-level least-privilege enforcement (namespaces, seccomp, cgroups), a denied action surfaces to the agent as a bare errno. Reading a blocked path returns "No such file or directory"; a blocked egress returns no route. The agent cannot tell "this file does not exist" apart from "policy removed this file," so it cannot adapt. It just sees a confusing failure and often retries the same thing.

This matters most in --headless, which auto-approves actions. The in-band approval step and the security analyzer are not in the loop there, so out-of-band enforcement is exactly where a lot of real deployments will land, and the agent is flying blind on why something failed.

Context on what I measured, so this is concrete and not hypothetical: I derived a least-privilege profile by tracing one real headless run, replayed it in observe mode with 0 would-deny across 23 execs and 5,498 file opens, then enforced it and the same task completed normally. The enforcement is out-of-band and works today. The missing piece is purely the explanation path back to the agent.

Proposed Solution

A hook or event seam that lets an external supervisor inject a structured observation into the conversation event stream in response to an action, so the agent receives "denied: write outside workspace (policy)" instead of a raw errno, and can adjust.

Enforcement stays entirely outside the SDK. The agent process runs inside the containment layer, so the walls hold regardless of what the SDK does. All I am asking about is whether there is (or should be) a clean way for an out-of-band component to turn a policy verdict into an in-band observation the agent understands.

I am not proposing the SDK ship any enforcement, take a dependency on my project, or maintain an integration. If the existing hook interfaces already allow injecting an observation like this, a pointer is all I need and you can close this. If they do not, my question is whether such a seam is something you would want to exist, or whether this is better kept entirely outside the SDK. "Keep it outside" is a fine answer.

Reference implementation, reproducible benchmark, and the full transcripts (including an uncontained vs contained A/B on a decoy credential) are here if useful: https://github.com/quantmlayer/quantmlayer

Alternatives Considered

Alternative today: parse errnos heuristically outside the agent, which is brittle. The reason I am raising it with the SDK rather than solving it entirely on my side is that the event stream is yours, and a supported seam would be stable where a workaround would not.

One clarification so it is not misread: nothing here is specific to OpenHands as a weakness. Any coding agent with shell access hits the same errno-opacity problem under external enforcement. I am raising it here because your CLI is open source and installs in one command.

Priority / Severity

Low - Nice to have

Estimated Scope

Small - API addition, config option, or minor change

Feature Area

• Agent API / Core functionality
• Tools / Tool system
• Skills / Plugins
• Agent Server
• Workspace management
• Configuration / Settings
• Examples / Templates
• Documentation
• Testing / Development tools
• Performance / Optimization
• Integrations (GitHub, APIs, etc.)
• Other

Technical Implementation Ideas (Optional)

No response

Additional Context

No response

Start with the SDK's existing hook interfaces and conversation event stream, especially the headless action path. Trace how tool or action results reach the agent and determine whether an external supervisor can inject a structured observation. Done means a documented maintainer decision or a clearly scoped API seam with defined behavior.