Explore environment-scoped managed execution

Environment-scoped managed execution — design discussion

Motivation

The current background Shell design is intertwined with the agent loop because
it owns run-scoped jobs through agent-private state. That is sufficient for a
short-lived background command, but it does not generalize to jobs that should
outlive a run, such as dev servers, watchers, long builds, or remote workloads.

The desired direction is to make Shell as ordinary a tool as possible while
supporting richer managed work.

Key ownership decision

A background job belongs to the environment that executes it, not to the
agent engine and not intrinsically to the session.

Session
  → selects / is granted an Environment
      → environment owns its execution capabilities
      → environment owns jobs created through those capabilities
      → host/service routes lifecycle notifications to authorized sessions

An environment may have multiple jobs; a future session may have access to
multiple environments. Jobs must be identified by an opaque,
environment-bound handle. A handle minted by environment A cannot inspect or
control a job in environment B.

Session association is for notification and authority routing, not process
ownership.

Why not generic agent-loop lifecycle subscriptions

Tools should not receive a broad subscription to agent-loop events. That would
expose unrelated facts and create shutdown/reentrancy hazards: other tool
calls/results, permission asks, user prompts, delegation activity, and
termination ordering.

Instead, the host/service should own lifecycle delivery. The engine should only
perform ordinary tool dispatch against the selected environment and apply normal
permission/guardrail decisions before a task starts.

Managed-work capability, not “background Shell”

The reusable abstraction is an environment’s managed execution capability:

Environment execution capability
  → accepts a capability-specific task request
  → returns an environment-bound opaque job handle
  → supports status, logs, cancellation, and completion
  → reports durable lifecycle events to the host/service

The common lifecycle concepts do not require common command syntax or a common
security model.

Examples:

Local workspace environment
  Shell
  SessionJobs

Kubernetes-hosted Starlark environment
  RunStarlark
  StarlarkJobs
  InspectStarlarkExecution

Remote build environment
  SubmitBuild
  BuildStatus
  BuildLogs
  CancelBuild

A secure Starlark environment must not pretend to be Shell. It should expose a
structured Starlark request and its own policy/audit semantics, for example:

{
  "program": "load(...) ...",
  "inputs": { "target": "…" },
  "limits": { "timeout_ms": 60000 }
}

This permits AST validation, module/host-operation allowlists, deterministic
limits, structured audit logs, workload identity, and no ambient host shell.
It may offer rich managed jobs while correctly offering no Shell capability.

Completion delivery

Completion should be event-driven rather than requiring model polling:

Environment reports a job lifecycle transition
  → service attributes it to session/environment authority
  → service persists a bounded, untrusted completion record
  → if session is active, queue for a turn boundary
  → if idle/reopenable, optionally initiate a controlled synthetic follow-up run

The service must not start a run concurrently with an active run, reset an
awaiting approval, or permit a flapping job to create unbounded agent runs.
Completion needs queueing/coalescing, explicit notification policy, and
per-session rate limits.

Authority and lifecycle constraints

• Starting work is authorized for the specific environment/capability/task.
• Stop, restart, and changed task arguments are distinct authorized actions.
• Output remains untrusted model input and must be bounded/framed.
• Environment placement/identity must remain exact; jobs do not silently follow
  a session into another workspace.
• Each environment defines cleanup, expiry, resource budgets, and restart
  behavior. A host restart must either reattach honestly or report a lost job.
• Session/environment grants can be revoked; completion delivery and control
  must reauthorize rather than assume permanent session ownership.

Deferred design work

This is not part of the Bash → Shell rename. It requires a dedicated acceptance
plan and likely an ADR because it changes execution ownership, session
notification behavior, durable resources, multi-environment authority, and
restart semantics.

Before implementation, settle:

1. environment discovery/selection and authority grants;
2. opaque job-handle format and routing;
3. lifecycle persistence and host-restart semantics;
4. notification targeting/coalescing/rate limits;
5. dev-server start/status/log/stop/restart/readiness behavior; and
6. the minimum generic lifecycle protocol versus capability-specific task APIs.

Start with the ownership, completion-delivery, and authority sections, then review the six deferred design questions. Done means producing the dedicated acceptance plan and likely ADR, with decisions for environment grants, opaque handles, persistence and restart behavior, notification limits, dev-server lifecycle, and capability-specific APIs.