security: define agent-loop authority, trust boundaries, and audit contract #2599

Goal

Define and enforce the authority, trust, and credential boundary for Base's deterministic agent loop before it can mutate GitHub state or consume external-agent output.

Background

The loop consumes issue bodies, pull-request text, repository documents, hosted-check output, and local command output. Those inputs are untrusted data and may contain prompt injection, secrets, or instructions that must not expand the loop's authority. The current loop contract (#2576) mentions security, but does not define token scopes, approval points, or audit requirements. The MCP threat model (#2589) covers documentation/index serving, not the broader controller.

Tracking: #2555.

Scope

• Publish an agent-loop threat model covering issue/PR/comment text, CI logs, repository files, branch names, commit messages, model output, and GitHub API failures as untrusted inputs.
• Define authority profiles for L0 reporting, L1 select/claim/prepare, L2 draft-PR proposal, CI observation/repair, and any future merge capability.
• Specify minimum GitHub token scopes, credential sourcing, secret isolation, redaction, and the rule that model output never grants authority.
• Require explicit human approval for any push, PR state change, merge, release, ruleset, workflow, installer, trust, or security mutation unless a separately approved policy permits it.
• Add audit events for every GitHub mutation, approval, denial, lease takeover, and stop condition.
• Add offline fixtures for malicious issue text, injected CI output, secret-shaped values, denied paths, token failures, and attempted authority escalation.

Acceptance Criteria

• docs/agent-loop-security.md defines the threat model, authority profiles, approval points, and GitHub permission matrix.
• The design: agent loop contract - state machine, event schema, autonomy levels #2576 event schema records authority profile, approval evidence, and mutation outcome without secrets.
• Fixtures prove untrusted issue/CI/document content cannot change the selected action, path boundary, or authority level.
• Secret values never appear in handoff bundles, ledger events, or failure summaries.
• The controller refuses to start when the required credential or approval state is ambiguous.

Validation

BASE_CLI_SOURCE_DIR=../base-cli/lib/python \
PYTHONPATH=../base-cli/lib/python:lib/python:cli/python \
python -m pytest tests/contracts <new agent-loop security tests>
git diff --check

Non-Goals

• Do not implement a model runtime or provider-specific prompt protocol.
• Do not enable automatic merge or release publication.
• Do not grant Base access to repository secrets.

Project Fields

• Status: Ready
• Priority: P1
• Area: Security
• Initiative: Agentic Coding Platform
• Size: M
• Milestone: v1.12.0
• Category: security

Agent Assignment

Assignee: codeforester. Human-first security design with implementation-ready contract tests; use an issue-backed worktree.