Tasks and policy

Publish narrow AgentCall tasks, grant them to callers or rosters, and test the effective policy.

Tasks define what an answering agent is asked to do and which capabilities it receives. Policy defines who may invoke each task.

1. Scaffold a task

agentcall task new architecture-history

Edit ~/AgentCall/<line>/tasks/architecture-history/SKILL.md:

---
description: Explain why past architecture decisions were made.
keywords: [architecture, migration, adr]
tools: [read]
workdir: /absolute/path/to/the/repository
---

Use ADRs, commit history, and current code to explain the decision.
Call out uncertainty instead of inventing rationale.

Only description is required. Optional fields are name, keywords, examples, tools, timeout_s, workdir, and threadable. The directory name is the task ID.

2. Validate before publishing

agentcall lint
agentcall policy
agentcall card

lint checks task manifests, effective policy assertions, and the rendered card. The other commands make the final grants and working directories visible for human review.

3. Grant access

# Everyone in the organization may request it
agentcall offer architecture-history

# Only one caller gets the extra task
agentcall allow ken architecture-history

# Remove a named grant or public offer
agentcall revoke ken architecture-history
agentcall unoffer architecture-history

# Deny a caller completely
agentcall block spammer

Policy verbs republish the card automatically. agentcall card push republishes after a direct policy-file edit.

Add policy assertions

Assertions prevent an accidental edit from silently widening access:

{
  "default_offer": ["ask"],
  "callers": {
    "ken": { "offer": ["architecture-history"] },
    "stranger": { "offer": [], "block": true }
  },
  "tests": [
    { "caller": "ken", "accept": ["architecture-history"], "deny": ["exec"] },
    { "caller": "stranger", "deny": ["*"] }
  ]
}

A failed assertion blocks policy edits and listener startup rather than falling back to the last-looking configuration.

exec is broad local authority. Shell commands can read, change, and send data outside a task working directory. Codex cannot enforce the same file-read boundary as Claude. Grant write, fetch, or exec only after reviewing the security model.

Success check

agentcall lint exits successfully and agentcall card shows the intended task, audience, capabilities, and working directory—nothing more.

Source of truth: README task and policy behavior.