# CoderAgent → Authorized Execution Integration Report

**Date:** 2026-10-01  
**Scope:** Phase 7 execution path through Ptah's CoderAgent

## Result

Ptah's `CoderAgent` now runs tasks that include `code` and `language` through
`AuthorizedExecutionService`. The service evaluates the agent's required
permission scope and policy, waits for human approval when policy requires it,
then invokes the configured `ExecutionProvider`. Ptah uses Bubblewrap by default
and has no plain-process fallback.

The agent returns captured output, exit status, timeout status, and execution
metadata in the step result. Permission, approval, and execution audit events
carry the same task ID. Requests without `code` keep the existing prototype
behavior, which does not claim to execute source code.

## Request path

```mermaid
flowchart LR
    R[Ptah roadmap step<br/>code + language] --> D[TaskDispatcher]
    D -->|registered identity + task policy| C[CoderAgent]
    C --> G[AuthorizedExecutionService]
    G --> P[PermissionGateway<br/>identity scope + policy]
    P -->|deny / missing scope| X[Audit denial<br/>no sandbox call]
    P -->|approval required| A[ApprovalManager]
    A -->|deny / timeout / unavailable| X
    A -->|approved| B[Bubblewrap provider]
    P -->|allow directly| B
    B --> S[Isolated Python or shell<br/>private network + workspace]
    S --> O[Captured result]
    O --> G
    G -->|TOOL_RESULT audit| C
    C -->|AGENT_FINISHED audit| D
    D --> Z[Ptah step result]
```

## Changes

- `CoderAgent` accepts an optional `AuthorizedExecutionService` and routes code
  tasks through it. Invalid inputs, denied actions, unavailable approval, and
  sandbox failures produce failed agent results rather than simulated success.
- `PtahBridge` constructs a secure execution service using its shared
  `PermissionGateway`, `AuditLog`, configured `ApprovalManager`, and an injected
  provider or the default `BubblewrapExecutionProvider`.
- The dispatcher records identity/policy decisions and agent start/finish
  events, correlated by task ID. The execution service records approval and
  tool invocation/result events.
- Missing identity, identity/registry mismatch, missing scopes, missing
  approval infrastructure, and rejected approvals fail closed.
- Added end-to-end coverage for approved code execution, missing execution
  scope, explicit approval, rejected approval, absent approval infrastructure,
  and correlated audit records.

## Verification

- `PYTHONPATH=src python3 -m pytest -q`: **275 passed** in 6.12s.
- `python3 -m ruff check .`: passed.
- `git diff --check`: passed.
- `python3 -m mypy --cache-dir=/tmp/cyberbrain26-mypy-final2 src/cyberbrain26`:
  passed with no issues in all 50 source files.
- Bubblewrap tests exercised Python and shell, private network namespace,
  workspace write access, host sibling-file isolation, timeout, output cap, and
  fail-closed behavior when Bubblewrap is unavailable.

## Remaining limits

- SAFE-mode identities have no execution scopes by default. Deployment code
  must explicitly grant `python` or `shell` scope and configure approval review.
- Approval state, task state, and audit events remain in memory and are lost on
  process restart.
- Bubblewrap is Linux-specific and exposes read-only system runtime trees; the
  selected workspace is writable by the executed code. These tests establish
  basic isolation behavior, not resistance to every hostile-code attack.
- BrowserAgent and other roles are not wired to execution. Model/provider calls
  and other external integrations remain separately configured.
- The existing repository has staged and unstaged user changes. They were
  preserved; no commit or push was made.