Historical comparison. The current proposal uses a separate public authored proto, keeps
binariesas[{path: ...}], treats omitted and empty binaries as matching no process, usesportsonly, and adopts the full proto matcher shapes. See the links under "Current design" below.
This gist shows one policy twice:
01-authored-policy-v1.yamluses the YAML shape owned by the handwritten policy model in PR #3334.02-current-runtime-proto.yamlshows the same policy in the shape of today'sSandboxPolicyprotobuf. It uses canonical ProtoJSON field names, but the data is written as YAML so the two files are easy to compare.
The second file is not a proposed v2 format. It shows what would happen if OpenShell reused the current runtime protobuf as the authored schema without redesigning it.
| Current policy YAML | Current runtime protobuf | Why |
|---|---|---|
filesystem_policy |
filesystem |
The handwritten model and runtime message use different field names. |
include_workdir, network_policies |
includeWorkdir, networkPolicies |
ProtoJSON prints field names in lower camel case by default. Parsers must also accept the original protobuf field name, so snake case can still work as input. |
port: 443 |
port: 443 and ports: [443] |
The current conversion fills both runtime fields for backward compatibility. A new authored schema should choose one representation. |
mcp.max_body_bytes |
endpoint-level jsonRpcMaxBodyBytes |
The authored model groups MCP settings. The runtime message stores the shared JSON-RPC body limit on the endpoint. |
tool: repo_* |
params.name.glob: repo_* |
tool is authoring shorthand. The runtime matcher uses the generic JSON-RPC parameter map. |
query.state: open |
query.state.glob: open |
The authored model accepts a scalar matcher. The protobuf matcher is always a message. |
The runtime message also contains advisorProposed and providerCredentialed. They do not appear in the example because both are false, but their presence in an authorable message would be a security mistake.
Standard ProtoJSON accepts null for most fields and treats it as unset. Today's authored parser rejects explicit null where presence matters. A Proto-backed YAML loader needs a check before ProtoJSON decoding if we want to keep that behavior.
We should not make policy authors use the second file as-is. Most of its churn comes from using a runtime message for an authoring job.
A v2 authored protobuf keeps filesystem_policy, nested mcp options, and
binary objects with path. It removes runtime-owned fields, uses the full
protobuf matcher objects instead of scalar shorthands, and emits canonical
snake-case names. Basic portable validation is declared with Protovalidate,
while the gateway retains context-dependent checks.
This comparison supports OpenShell issue #3388.