Tasks and policy

Publish narrow AgentCall tasks, set what each caller may be told, and test the effective policy.

Tasks define what an answering agent is asked to do. Policy defines how much of what it finds may reach each caller.

1. Scaffold a task

agentcall task new architecture-history

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

---
description: Explain why past architecture decisions were made.
keywords: [architecture, migration, adr]
---

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, timeout_s, and threadable. The directory name is the task ID. Unrecognized keys are rejected rather than ignored, so a stale field is a startup error and not a silent no-op.

2. Validate before publishing

agentcall doctor

doctor is the single read-only view of task validity, effective policy, working scope, and card drift. Add --json for the same structured result.

3. Decide who is answered

Any caller you have not blocked can request any task. What bounds the answer is what the task read, not which task ran: a path outside every root, or on the denylist, is refused at the read — before the agent sees it. The answer itself is not inspected.

This does not bound Bash. A caller can reach any file on the machine through a shell command; the guard records it and allows it, because a command string cannot be inspected for what it will read. The roots and the denylist shape what the agent reaches by default — they are not a boundary against a caller who asks for something else. See #419.

Who gets answered is a separate, yes/no question. Everyone answered sees the same thing — the organization is the boundary, not a per-caller level.

# Deny a caller completely — beats the default
agentcall block spammer
agentcall unblock spammer

# Answer only named callers
agentcall access --default blocked

Offline delivery is a separate owner opt-in and defaults to disabled:

agentcall access --offline enabled
agentcall access --offline disabled

Enabling it republishes the installation card with durable-mailbox-v1. Disabling it stops new durable admissions; queued work is revalidated before lease and becomes terminal revoked if delivery remains disabled.

secret is not grantable. It means “never leaves this machine”, so no caller and no caller can reach it.

Policy verbs republish the card automatically. After a direct policy-file edit, review the change and publish explicitly:

agentcall doctor
agentcall admin card publish

Add policy assertions

Assertions prevent an accidental edit from silently widening access. Each pins whether one caller is answered, which is what actually governs whether anything leaves:

{
  "default_access": "blocked",
  "callers": {
    "ken": { "access": "allowed" },
    "stranger": { "access": "blocked" }
  },
  "tests": [
    { "caller": "ken", "expect_access": "allowed" },
    { "caller": "stranger", "expect_access": "blocked" }
  ]
}

A named caller rule overrides the installation default.

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

scope.json names a root the agent may read under, and a denylist that holds regardless. A path you never thought about is readable — the default root is $HOME, so anything a subdirectory later acquires is in scope too. With Codex none of this is enforced. There is no read guard there at all, so nothing stops a denied read, and nothing inspects the answer. Review the security model before widening a root.

Success check

agentcall doctor exits successfully, shows the intended tasks, default access, each named caller’s resolved access, mailbox capability, key-ring and execution journal health, and a current card publication.

Source of truth: README task and policy behavior.