# agnoclaw v0.2 Harness Core Spec

Status: Active draft (implementation-aligned)
Audience: Harness maintainers, platform integrators, enterprise platform team
Last Updated: 2026-02-24

## 1. Purpose

`agnoclaw` v0.2 defines the harness core, not the enterprise control plane.

The harness core must:
- Run agents locally or embedded in another service.
- Expose stable policy, hook, event, and context contracts.
- Stay compatible with Agno runtime primitives.
- Be extensible for enterprise integration without forcing an enterprise dependency.

The enterprise platform repo should own provisioning, org management, policy distribution UX, compliance workflows, and hosted multi-tenant operations.

## 2. Research Inputs and Design Implications

As of February 24, 2026, design choices are based on three primary sources.

### 2.1 Agno (normative runtime base)

Observed in Agno docs:
- `run/arun` plus streaming and run events are first-class runtime APIs.
- Tool hooks (`pre_hook/post_hook` and tool hook chain) are official extension points.
- Run context (`run_id`, `session_id`, `user_id`, metadata) is a documented contract.
- AgentOS provides hosted/API interfaces and middleware for JWT and RBAC.

Implication for v0.2:
- Harness execution contracts must follow Agno directly.
- Tool policy enforcement belongs at tool-hook boundaries.
- Context propagation must be explicit and typed.
- AgentOS is optional compatibility profile, not a hard dependency.

### 2.2 Claude Code (workflow and policy patterns)

Observed in Anthropic Claude Code docs:
- Hooks and matchers are explicit governance points.
- Permission modes are explicit runtime behavior controls.
- Memory hierarchy is layered (enterprise/user/project/local).

Implication for v0.2:
- Keep explicit, auditable lifecycle checkpoints.
- Keep policy and guardrail behavior deterministic and fail-mode configurable.
- Keep prompt/workspace memory deterministic; platform repo can add enterprise hierarchy later.

### 2.3 OpenClaw (operations and extensibility patterns)

Observed in OpenClaw docs:
- Clear separation between gateway/control plane concerns and execution modules.
- Security posture is layered (auth, rate limits, monitoring, deployment hardening).
- Scheduler model supports heartbeat/cron patterns for continuous operation.
- Skills are a first-class extensibility surface.

Implication for v0.2:
- Keep harness core small and composable.
- Keep security controls enforceable in runtime (path/network/tool policy).
- Keep skill and scheduler surfaces in harness; keep fleet governance in platform.

## 3. Product Boundary

### 3.1 In this repo (required)

- Agent harness runtime.
- Typed context, hooks, policy, and events.
- Local/embedded tool execution and guardrails.
- Skill loading and one-shot skill prompt injection.
- Compatibility adapters for external platform context.

### 3.2 In enterprise platform repo (out of scope here)

- Org/tenant lifecycle and identity federation.
- Admin policy authoring and approval workflows.
- Hosted API gateways and SRE runbooks.
- Centralized analytics and compliance workflows.

## 4. Runtime Contract

### 4.1 Run API

Harness must provide:
- `run(...)` and `arun(...)` with stream and stream-events support.
- One-shot skill activation.
- Explicit context injection (`ExecutionContext`).
- Stable error surface (`HarnessError`).

### 4.2 Execution context

`ExecutionContext` is immutable and includes:
- `user_id`, `session_id`, `workspace_id`
- optional `tenant_id`, `org_id`, `team_id`
- `roles`, `scopes`, `request_id`, `trace_id`
- metadata map

### 4.3 Lifecycle checkpoints

Policy checkpoints:
- `before_run`
- `before_skill_load`
- `before_prompt_send`
- `before_tool_call`
- `after_tool_call`

Hook checkpoints:
- pre-run hook chain
- post-run hook chain

### 4.4 Events

Core events include:
- `run.started`, `run.completed`, `run.failed`
- `prompt.built`
- `model.request.started`, `model.request.completed`
- `skill.load.started`, `skill.load.completed`
- `policy.decision`
- tool events: `tool.call.started`, `tool.call.completed`, `tool.call.failed`
- guardrail events: `guardrail.violation`

## 5. Tool Guardrail Layer

v0.2 guardrails are runtime-enforced before tool execution.

### 5.1 Path guardrails

- Evaluate path-like arguments (`path`, `base_dir`, `working_dir`, etc.).
- Default allow root is workspace root when allowlist is not set.
- Explicit blocked roots are enforced before allowlist checks.

### 5.2 Network guardrails

- Global network enable/disable toggle.
- Optional HTTPS enforcement for URL tools.
- Optional host allowlist and denylist.
- Optional private/loopback host blocking.
- Optional heuristic network-command blocking in bash.

### 5.3 Failure behavior

- Guardrail denials return `HarnessError(code="GUARDRAIL_DENIED")`.
- Policy denials return `HarnessError(code="POLICY_DENIED")`.
- Fail-open/fail-closed for policy evaluation remains configurable (`policy_fail_open`).

## 6. Extensibility Contracts

### 6.1 Policy engine

Policy engine methods may return:
- `ALLOW`
- `DENY`
- `ALLOW_WITH_REDACTION`
- `ALLOW_WITH_CONSTRAINTS`

Redactions can be applied to:
- run input
- prompt payload
- tool arguments
- tool results

### 6.2 Event sink

Event sink is pluggable with two modes:
- `best_effort`
- `fail_closed`

### 6.3 Hook contracts

- Pre/post run hooks must preserve typed envelopes (`RunInput`, `RunResultEnvelope`).
- Hook failures map to stable hook error codes.

## 7. AgentOS Compatibility Profile (Optional)

### 7.1 Position

AgentOS is not required for harness correctness.

AgentOS should be adopted when at least two are required:
- hosted/API agent interfaces
- standardized auth middleware propagation (JWT claims)
- RBAC enforcement at hosted endpoint surfaces
- centralized hosted operations

### 7.2 v0.2 adapter contract

`AgentOSContextAdapter` maps claim payloads into `ExecutionContext`:
- user/session identity mapping
- tenant/org/team claim mapping
- role/scope normalization
- request/trace id mapping

This adapter is a compatibility seam, not a runtime dependency on AgentOS.

## 8. Configuration Surface (v0.2)

In addition to existing runtime config, v0.2 includes:
- `event_sink_mode`
- `policy_fail_open`
- `guardrails_enabled`
- `path_guardrails_enabled`
- `path_allowed_roots`
- `path_blocked_roots`
- `network_enabled`
- `network_enforce_https`
- `network_allowed_hosts`
- `network_blocked_hosts`
- `network_block_private_hosts`
- `network_block_in_bash`

## 9. Acceptance Criteria

### 9.1 Required tests

- Sync/async run lifecycle parity.
- Policy deny blocks model execution.
- Tool policy deny/redaction behavior.
- Guardrail denials for blocked path/network calls.
- Event envelope shape and context propagation.
- AgentOS adapter claim mapping smoke tests.

### 9.2 Completion gate for v0.2 harness core

v0.2 core is complete when:
- Required contract tests pass.
- Embedding docs exist and are implementation-accurate.
- AgentOS compatibility adapter + smoke test exists.
- Tool-boundary policy and guardrail enforcement are active.

## 10. Remaining Work After v0.2 Core

- Optional async-aware tool-policy hook path for async-only policy callbacks.
- Policy packs and reusable policy templates for common enterprise controls.
- Expanded adapter examples for hosted AgentOS interface deployments.
- Platform-repo implementation of enterprise memory hierarchy and governance UX.

## 11. References (Primary Sources)

### Agno
- Running agents: https://docs.agno.com/introduction/agents/running-agents
- Tool hooks: https://docs.agno.com/agents/hooks/tool-hooks
- Run context: https://docs.agno.com/reference/run/run-context
- Guardrails intro: https://docs.agno.com/guardrails/introduction
- AgentOS intro: https://docs.agno.com/agent-os/introduction
- AgentOS interfaces: https://docs.agno.com/agent-os/interfaces/introduction
- AgentOS JWT middleware: https://docs.agno.com/agent-os/middleware/jwt
- AgentOS RBAC middleware: https://docs.agno.com/agent-os/middleware/rbac

### Claude Code
- Hooks: https://docs.anthropic.com/en/docs/claude-code/hooks
- Settings and permission modes: https://docs.anthropic.com/en/docs/claude-code/settings
- Memory: https://docs.anthropic.com/en/docs/claude-code/memory

### OpenClaw
- Docs home: https://docs.openclaw.ai/
- Architecture: https://docs.openclaw.ai/architecture
- Security: https://docs.openclaw.ai/security
- Cron jobs: https://docs.openclaw.ai/cron-jobs
- Skills: https://docs.openclaw.ai/skills
- Project README: https://raw.githubusercontent.com/openclaw/openclaw/main/README.md
