Strict Pointer Protocol | AGN Architecture

>> Change Log Change Log

[ 2026-03-01 ] Documentation clean-up (content aligned to current AGN)

This update only aligns content, while preserving the original visual language and structural framework.Focus: remove old phase-based narratives and descriptions that drifted from implementation, and update everything to the current AGN architecture (pointer_v1, provider registry, multi-instance sync, validation directory refactor).

agentsetup/agenttools: Adjust the old staged delivery narrative to the current modular runtime semantics.
codex-acceptance/remark: Remove obsolete terms and complete current commands and paths (scripts/validation/*).
index/workflow/agreement page: Updated to the tone of "implemented" and removed the expression "proposal status".
Add this changelog as the anchor point for this content cleaning audit.

>> Threat Model & Objectives Risk Model & Objectives

[ RISK_VECTORS ] Core Risks and Reflections

An audit based on the previous generation protocol revealed a serious idealistic vulnerability: directly passing the original file path will introduceDirectory traversal injection (Path Injection)Risk; exists when writing concurrentlyPointer invalidation and race conditions;and redefining "local SSOT" would create serious conflicts with the existing GitHub/JSON control planeSplit-Brain。

In addition, giving large models unrestricted reading tools will still cause Context explosion, and the far-left strategy of "never pass long text" will directly lead to process deadlock when reading fails.

[ OBJECTIVE ] Bi-plane controlled solution

Reconstruct the AGN architecture intoDual Plane, by introducing strictLogical ReferenceandControlled Tools, on the premise of not destroying the existing Coordinator lock mechanism and approval gate control, achieving safe, auditable, and non-exploited on-demand context loading.

Goal: Strip off extremely large execution log loads while ensuring strong traceability consistency and system fault self-healing capabilities.

>> Rigorous Implementation Rigorous implementation steps

Create Dual Plane Architecture

Avoid conflicts between two truths. keep originalssot/dispatch/resultsdirectory as the onlyControl Plane. New.agn_workspace/tasks/as append-onlyArtifact PlaneStore large logs.

# Control Plane (Immutable Truth): ssot/dispatch/verdicts/... (JSONs keeping locks & auth) # Artifact Plane (Payload Carrier): .agn_workspace/tasks/<task_id>/<attempt_n>/ ├─ manifest.json # Allow downstream reading only when ready=true ├─ diff_snapshot.patch └─ execution_log.txt

Logical Pointer Protocol and Tamper Resistance (Logical Pointer Protocol)

Coordinator never issues bare paths (absolute or relative paths). Dispatch and Verdict messages only carryartifact_refs, passing parameters via a tamper-proof reference URI.

"Task failed. Fetch artifact for context: { "artifact_refs": [ { "ref": "agn://task/123/attempt/2/artifact/error_log", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "size_bytes": 14502 } ] }"

Force Controlled Artifact Tools

Disable Agent from using basic bashcatOrder. Encapsulate a unified tool layer and intercept any soft link escapes and large file loading. Large models must interact through secure APIs.

Available Tools for Agent: - agn_read_artifact(ref, mode="tail", lines=200) - agn_search_artifact(ref, pattern="Exception", max_matches=5) [Security Gate]: Tool layer verification ref -> map real path -> compare sha256 -> perform truncation -> return.

Concurrency & Fallback

Strictly follow atomic placement (tmp + fsync + replace) when writing. When an extreme situation occurs (pointer reading fails), the system automatically triggers the bailout mechanism to prevent deadlock.

# Fallback Mechanism: If Agent fails to read `agn://...`: Coordinator degrades gracefully by injecting restricted summary (e.g., Bottom 4KB + hash) into Prompt, logging `fallback_reason`. # Budgeting: Max 8 reads per attempt; Max 32KB per read. Timeout throws structured error.

>> Migration & Acceptance Migration planning and acceptance

// METRIC — 01

Strong consistency audit (Auditability)

It is not only necessary to check whether the log has been read, but also to verify the accuracy of the reading. All control plane JSON must contain the SHA-256 hash of the referenced artifact, ensuring postmortem review is 100% traceable to the exact bytes seen by the larger model.

HASH_MATCH: Control Plane vs Manifest

// METRIC — 02

Token Budgeting

Monitor the Token flow rate through audit logs. Even if the Agent falls into a reading loop, it must be physically truncated and report a timeout (Timeout) after 8 reads or reaching 32KB to prevent bottomless consumption.

LIMITS: Max 8 Reads / Max 32KB per query

// METRIC — 03

Smooth upgrade observation (Rollout Window)

Code reconstruction is launched in stages: 1. Write Manifest to be compatible with old logic -> 2. Deploy `agn_read_artifact` to force Reviewer access -> 3. Cut off plain text prompts. Observe the timeout rate and backtracking success rate in the first week.

METRIC: Fallback trigger rate < 5%