Remediation Playbook

Use this sequence when an Agent CLI unexpectedly changes routing, creates remote resources, or gains access to unrelated credentials. The order matters: contain first, rotate second, clean up last.

Phase 0: Freeze side effects

• Pause publishing, deployment, deletion, account changes, and automatic retries.
• Choose one human-approved writer for each external platform.
• Treat timeouts as unknown results. Read back remote state before retrying.
• Preserve timestamps and configuration metadata, but never paste credential values into tickets.

Exit condition: no background process can create additional remote resources.

Phase 1: Establish the effective route

Inspect every layer that can influence tool choice:

1. User-level Agent instructions
2. User-level Skill pools
3. Host-specific Skill directories
4. Symlinks and Windows Junctions
5. Project instructions and trusted-project configuration
6. Package install and upgrade hooks
7. Bridge configuration and running processes

Classify each rule:

Route type	Safe default
Explicit platform command	Allowed within the named task
Project-owned route	Allowed only inside that project
User-level implicit route	Disable or narrow
Installer-created route	Require disclosure and opt-in

Phase 2: Contain credentials

1. Stop the process that is persisting or redistributing environment data.
2. Record only the affected credential names, scopes, and timestamps.
3. Remove stale environment snapshots and caches through a reviewed manual change.
4. Restrict credential files to the owning user or service identity.
5. Replace user-level environment variables with task-scoped injection.
6. Rotate credentials that remained valid during the exposure window.
7. Restart only the minimum required processes and verify their child environments.

Rotation before containment can immediately expose the new credential to the same bridge, so do not reverse steps 1 and 6.

Phase 3: Narrow routing

Use the explicit routing policy template. A compliant route should answer all of these questions:

• Did the user explicitly name the external platform?
• Is the route limited to one task class or project?
• Does the delegated agent need any credential?
• Which external writes are permitted?
• Who owns idempotency and read-after-write verification?
• How is the route disabled and how is reinstallation detected?

Phase 4: Restore least privilege

• Default to workspace-scoped writes.
• Require approval for network writes, publishing, deployment, deletion, credential changes, and account settings.
• Keep unrestricted access time-bound to one operation.
• Remove stale trusted-project entries.
• Review global hooks and rules; move project-specific behavior into the owning repository.
• Restore deletion confirmation in agent-capable editors.

Phase 5: Make external writes idempotent

Every external create or update operation should carry:

• a stable operation key derived from business intent
• one writer lease or lock
• a local attempt record that contains no credential values
• a read-after-write check
• an explicit terminal state: confirmed, failed, or unknown

On timeout:

1. Mark the operation unknown.
2. Query the external platform by operation key or deterministic metadata.
3. Reuse the confirmed result if it exists.
4. Retry only when absence is proven.

Phase 6: Verify durability

Run the auditor:

agent-scope-guard --json --fail-on high

Then verify again after:

• reboot or user sign-in
• Agent host upgrade
• vendor CLI upgrade
• package reinstall
• a new project becoming trusted
• credential rotation

The remediation is complete only when the route stays narrow after those lifecycle events.