Chapter 7: Tool Use and Agentic Workflows
1. Chapter Overview
Tool use turns an AI system from a producer of information into an actor inside another system. A generated answer may be wrong; a tool call can transfer money, alter a record, notify a customer, start a job, or grant access. Once external effects become possible, response quality is only part of the engineering problem. Before execution, the system has to prove that the proposed action and its parameters fall within authority and that any approval covers the exact effect. Afterward, it needs enough evidence about the outcome to continue safely.
Agentic workflows compound the problem because they may plan, choose tools, wait, revise, delegate, and resume after interruption. Each step can cross an authority boundary. Permission that was current when the task began may be stale by the time a later action reaches dispatch. Production designs should therefore grant bounded authority for named actions under explicit conditions, never a general ability to “complete the task.”
The primary engineering decision in this chapter is:
What authority may cross the tool boundary, for which exact action, under which conditions, and with what evidence of outcome?
This chapter owns the action-specific contracts behind tool calling, approval gates, idempotency, delegation, long-running tasks, and human-in-the-loop execution. It consumes consequence and accountability classifications from Chapter 3 and the action-ready workflow boundary from Chapter 6. Identity, access-control policy, and governance remain with Chapter 9; evaluation strategy, release mechanics, and operational telemetry remain with Chapters 8, 10, and 11. The concern here is narrower: the point where a model-selected proposal may become an external effect.
2. Primary Engineering Problem
Systems that can act need boundaries stronger than intent.
“Use tools carefully” is not a permission model. Giving a model access to a tool does not authorize that tool for the current user, and a plausible plan does not amount to approval. Nor does a successful transport response prove that the intended effect completed. If the previous attempt timed out, uncertainty about its outcome makes a retry more dangerous, not automatically safe.
The engineering problem is to convert a probabilistic proposal into a deterministic, attributable, recoverable action. Five questions frame every consequential dispatch:
- Who is acting? Identify the initiating principal, any represented principal, the executing component, and the accountable owner.
- What exact effect is proposed? Resolve the semantic operation, target, material parameters, consequence, and expected postcondition into one canonical representation.
- Why is it allowed now? Consume an authoritative permission decision, required approval, current preconditions, and time or quantity limits.
- How will repeats and uncertainty be handled? Define effect identity, commit semantics, reconciliation, partial success, cancellation, and compensation limits.
- What proves the outcome? Produce a structured receipt that relates proposal, authorization, approval, dispatch, and confirmed or unresolved effect.
If any answer is indeterminate, the model cannot supply the missing authority. Keep the action in proposal, narrow it, send it for review, or reject it.
3. Core Mental Model
A tool call is a proposed authority crossing
A model may select a semantic action and propose values; the execution boundary decides whether the resulting proposal is admissible. Capability does not erase this separation. Model confidence cannot establish identity, expand resource scope, waive approval, or turn an unknown outcome into success.
Control the canonical action envelope, not a raw API call or natural-language plan. At minimum, that envelope contains:
- action and action-version identity
- semantic operation and tool-contract identity
- initiating principal and represented principal, if different
- workflow purpose and accountable owner
- target resources, tenancy, and environment
- material parameters with source and authority metadata
- consequence and reversibility class
- preconditions, limits, and explicit deny conditions
- authorization decision identity, version, and expiry
- approval reference and action digest where required
- effect identity and proposed recovery contract
Canonicalization comes before authorization, approval, idempotency derivation, and dispatch, so every control sees the same versioned representation. If the system resolves an account alias, adds a default notification audience, or normalizes an amount, those resolved values belong to the action under review. Downstream defaults or ignored fields must not silently widen it.
Parameter provenance is part of authority
For every consequential parameter, declare both its origin and the influence the model may exert:
- User-supplied: explicitly provided by the initiating principal.
- Model-proposed: suggested by the model and subject to constraints or approval.
- System-derived: resolved from trusted workflow state or an authoritative source.
- Policy-fixed: set by an authority decision and not mutable by the model.
- Protected: hidden from or immutable to the model, such as tenant, credential, or environment boundaries.
- Tool-returned: received as data with provenance, freshness, completeness, and trust labels.
A model might propose a message body while remaining unable to select the tenant, sender identity, environment, or maximum amount. In practice, narrow parameter authority often matters more than a narrow tool name.
Actions have an effect lifecycle
An external action rarely moves cleanly from “called” to “succeeded.” The effect lifecycle may need to distinguish:
- proposed
- canonicalized
- authorized
- approval-pending
- approved
- dispatched
- acknowledged
- outcome-unknown
- confirmed
- partially completed
- cancelled before dispatch
- compensated
- rejected
- terminally failed
The full set is not a mandatory state machine for every tool. Any side-effecting action does, however, need clear distinctions between acknowledgement and completion, known failure and unknown outcome, and cancellation before versus after its commit point.
A tool request passes from proposal through policy and bounded approval to execution, effect receipt, and reconciliation.
System view
Authority and Evidence Carry an Action Across the Tool Boundary
Text equivalent
- 1. The requester supplies the initiating principal, purpose, target, and intended outcome; missing identity or scope stops intake before proposal.
- 2. The orchestrator records the bounded request and asks the model for one candidate semantic action, not for general execution authority.
- 3. The model proposal contributes suggested parameters and rationale; its proposal record carries no permission to dispatch.
- 4. The policy gate canonicalizes the target and material values, then consumes the current authority decision and approval rule.
- 5. A denied, stale, contradictory, or indeterminate decision moves the action to Refused or unresolved with its reason recorded.
- 6. A pre-authorized action may proceed directly to the tool adapter; an action requiring judgment goes to the human approver.
- 7. The human approver sees the exact action digest, evidence, consequence, uncertainty, and allowed decisions; rejection, expiry, or material change stops that version.
- 8. Approval authorizes only the reviewed action version, which the tool adapter dispatches with a stable effect identity.
- 9. The external system may reject, acknowledge, partially commit, or complete the side effect; a transport response alone does not establish completion.
- 10. The effect receipt records acknowledgement, remote operation identity, and available outcome evidence without treating missing evidence as success.
- 11. A timeout, partial result, or ambiguous receipt enters reconciliation before the orchestrator may continue or repeat the effect.
- 12. Reconciliation queries the stable operation identity and compares the observed postcondition with the authorized action.
- 13. The tool adapter may retry only when reconciliation establishes that the prior effect is absent and repeat execution remains authorized.
- 14. Reconciliation returns a confirmed, partial, absent, or still-unknown outcome and its evidence to the orchestrator.
- 15. If authority or outcome remains indeterminate, Refused or unresolved records the stop; neither model narration nor available retry budget can override it.
Receipts, not narration, prove action
A model summary may help a user understand the result, but it is weak evidence of action. The structured receipt identifies the authorized action, the actual dispatch, and the outcome currently known. Sensitive payloads can remain behind access-controlled references; stable identities, material digests, timestamps, and evidence links provide accountability without duplicating secrets.
4. System Boundary
Chapter 7 begins when the harness presents an admissible candidate action. It ends when the action boundary returns an effect-specific outcome and receipt. The contracts between those points are this chapter's concern.
Chapter 7 owns
- semantic action and tool contracts
- effective principal and represented-principal binding at execution
- parameter provenance, protected fields, and action canonicalization
- permission consumption and action-specific approval payloads
- effect identity, idempotency, ambiguous-outcome reconciliation, and compensation limits
- delegation envelopes and authority attenuation
- effect safety for long-running tasks
- result provenance and minimum action receipts
Chapter 7 does not own
- how business risk and accountability classes are established
- generic workflow orchestration, state machines, validation, and retry budgets
- identity systems, policy authoring, threat models, privacy rules, or governance review
- full evaluation methodology and launch thresholds
- deployment topology, credential release, or runtime configuration rollout
- telemetry storage, alerting, incident command, or post-incident process
- general multi-agent coordination theory
These handoffs matter in practice. Chapter 9 may decide that a principal can update records in only one tenant; at dispatch, Chapter 7 verifies that the canonical target is inside that tenant and records the governing decision. Chapter 6 may make a failed workflow step eligible for retry, but Chapter 7 still decides whether repeating its external effect is safe or must wait for reconciliation.
Four boundary rules
- Tool access is not tool authority. A callable operation may still be inadmissible for the current principal, purpose, target, or parameters.
- Planning is not execution approval. Approval of an objective or plan does not automatically approve material parameters chosen later.
- Human-in-the-loop is an action contract. Review must expose the exact action, evidence, consequence, uncertainty, and allowed reviewer decisions.
- Long-running work renews authority over time. A task cannot rely indefinitely on permissions, approvals, credentials, or the intent captured when it began.
5. Design Principles
Principle 1: Define semantic actions before exposing tools
Start with the smallest business action the workflow needs, not the broadest API an integration happens to expose. “Add an internal note to this case” is safer than “update case” because its target and consequence are reviewable. The resulting contract names its targets, material parameters, preconditions, postconditions, and effect class.
Principle 2: Prove effective authority at dispatch
At dispatch, resolve the initiating and represented principals, purpose, target scope, parameter envelope, limits, and authoritative permission decision. The executing credential is merely the mechanism used to act; it is not the source of legitimacy. Missing, stale, contradictory, or unnecessarily broad authority requires refusal.
Principle 3: Bind every material value to one action version
Resolve aliases, defaults, resource identifiers, amounts, audiences, and other consequential fields before asking for authorization or approval. Compute the action digest from that canonical representation. Any material change creates a new version and invalidates decisions that no longer match it.
Principle 4: Design for unknown outcomes, not “exactly once”
Across a distributed boundary, an unqualified exactly-once claim is rarely defensible. The contract must say who creates the idempotency identity, which semantic operation it represents, where deduplication occurs, and how long that protection lasts. After a timeout or disconnect, reconcile against an authoritative receipt or status interface before attempting the effect again.
Idempotency and compensation address different failures. The former prevents or recognizes duplicate intent. The latter creates a new effect intended to offset a completed action, so it may need separate authority and can itself fail or remain incomplete.
Principle 5: Gate consequence and bind the gate
Base approval on consequence, reversibility, and uncertainty rather than technical complexity. Its record binds the exact canonical action to an evidence snapshot, reviewer authority, decision, and expiry. If a material value changes later, the applicable rules decide whether the new action needs authorization, approval, or both.
Principle 6: Attenuate authority through delegation
A delegate normally receives less authority than its parent and must never receive more by implication. The delegation envelope preserves provenance, withholds unnecessary tools and data, constrains parameters and budgets, limits depth, and names the result's acceptance owner. A subtask assignment alone grants no permission to create external effects.
Principle 7: Separate durable progress from model narration
Committed checkpoints, action ledgers, and confirmed receipts—not narrative summaries—define progress in long-running work. After a restart, a worker should be able to determine whether an effect occurred without interpreting prose. A lease or equivalent single-writer rule keeps concurrent attempts from dispatching the same action.
Principle 8: Treat tool results as data
Treat a tool result as a payload with provenance and trust properties. It may be stale, partial, or contain instructions the workflow never authorized. Preserve its source, freshness, completeness, and scope. Placing returned text in model context does not give that text execution authority.
6. Architecture Patterns
Autonomy is an effect ladder
Autonomy levels describe action authority, not system maturity. A higher tier is useful only when its broader effect is justified and controlled.
| Tier | Permitted effect | Required control | Step down when |
|---|---|---|---|
| Observe | Read data without external mutation | scoped read authority, provenance, freshness | read scope is ambiguous or data is too sensitive for the workflow |
| Propose | Produce a candidate action only | canonical action envelope and evidence | the system cannot resolve a bounded target or parameter set |
| Prepare | Create a reversible draft in a bounded workspace | protected destination, version identity, discard path | the draft itself creates an external notification or durable commitment |
| Execute bounded | Perform pre-authorized low-consequence actions | narrow permission, parameter envelope, receipt, repeat safety | consequence, ambiguity, or scope exceeds the pre-authorized envelope |
| Execute approved | Dispatch one exact action after review | bound approval packet, action digest, current authority | parameters, evidence, consequence, or authority change |
| Orchestrate | Select among approved actions within an objective and budget | action catalog, cumulative limits, per-action authorization, stop conditions | the plan reaches an unapproved action class or cannot reconcile an outcome |
| Delegate | Issue attenuated subtask authority | delegation envelope, depth and budget limits, acceptance owner | the delegate would need broader authority or inherited approval does not cover its action |
Pattern 1: Read-only tool use
Read-only tool use fits workflows that need external information without mutation. Constrain the principal, resource scope, fields, purpose, and freshness, and return provenance with the result. If the boundary cannot prevent cross-tenant or over-broad queries, step down to no tool use. “Read only” does not mean harmless when the operation exposes data or changes a later decision.
Pattern 2: Drafted action
In this pattern, the system prepares a canonical action or reversible draft without dispatch authority. It suits decisions where a person must choose the target, consequence, or final content. Mark the output as unexecuted and expose both its evidence and unresolved fields. Beware of “draft” endpoints that notify someone, allocate a scarce resource, or otherwise become visible outside the workspace.
Pattern 3: Bounded write
A bounded write is appropriate for repeatable, low-consequence actions whose scope and parameters can be enforced deterministically. It still requires a narrow capability, protected resource boundaries, stable effect identity, declared commit behavior, and a receipt. Parameter choice, aggregation, or volume can turn an otherwise modest operation into a high-consequence one; in that case, reduce the envelope or require exact approval.
Pattern 4: Exact-action approval
Exact-action approval presents one canonical action with its targets, material parameters, consequence, reversibility, uncertainty, evidence, available preview or diff, authority reference, digest, expiry, and allowed decisions. The reviewer may approve, reject, edit, narrow, or escalate according to the packet. That decision applies only to the reviewed action version; plan-level approval cannot cover material values chosen later.
Pattern 5: Long-running action workflow
When work spans interruptions, waits, or multiple effects, define durable task and attempt identities first. Then specify the lease or single-writer rule, checkpoint contents, safe resume boundary, and an action ledger that distinguishes proposals from dispatched and confirmed effects. Stale authority or approval must be renewed. Cancellation, supersession, takeover, and late results need explicit behavior, and user-visible progress must follow the durable record.
Pattern 6: Delegated subtask
Delegation isolates bounded work; it cannot bypass the parent's controls. Its envelope names the parent execution, objective, input scope, allowed and withheld actions, parameter and consequence limits, budget, deadline, depth, approval inheritance, result contract, acceptance owner, and revocation behavior. The delegate returns results or proposed actions with provenance and has no route to amplify authority.
Composition example: timeout after a bounded write
Consider a workflow preparing an update to one authorized record. The user supplies the record reference, the system derives and protects the tenant, and the model proposes a status and note. Canonicalization resolves the record identifier, validates the status transition, and produces action version 3. Although the permission decision allows the update, its consequence rule still requires exact approval. The reviewer sees the target, diff, evidence, uncertainty, and action digest before approving version 3.
The system derives an effect identity from the semantic action, target, material-parameter digest, and workflow identity. Dispatch reaches the remote service, but the acknowledgement times out, leaving the outcome unknown. Available harness retry budget does not make another dispatch safe. Reconciliation queries the stable operation identity and discovers that the update completed. The system records the remote receipt, confirms the effect, and returns the original action receipt. If a second worker resumes the task, the confirmed ledger entry prevents it from sending the update again.
The example stays deliberately local to the action boundary. Chapter 6 defines the enclosing workflow transitions, while Chapter 8 determines the broader scenarios and thresholds used to evaluate the system.
7. Failure Modes
Failure mode 1: A broad endpoint substitutes for a narrow action
The workflow needs one operation but receives a general credential and arbitrary parameters. A model-selected field or target can then expand the blast radius without crossing another visible boundary.
Failure mode 2: The executing credential is mistaken for user authority
Because the tool accepts a service credential, the caller treats the action as legitimate. Yet the initiating or represented principal, purpose, resource scope, or decision source is absent.
Failure mode 3: Authorization and execution see different actions
Aliases, defaults, normalization, or tool-side behavior changes a material parameter after authorization or approval. The effect dispatched is no longer the action that was reviewed.
Failure mode 4: Approval covers a summary rather than an action
The reviewer approves persuasive prose or a high-level plan, then recipients, amounts, environments, or side effects change later. No renewed decision covers the action that reaches dispatch.
Failure mode 5: Timeout triggers a duplicate effect
The remote operation commits, but its response is lost. Without reconciling that unknown outcome, the workflow calls the tool again and produces duplicate notifications, updates, jobs, or transfers.
Failure mode 6: Partial completion is reported as success
A bulk action affects some targets and fails others, or the caller mistakes asynchronous acknowledgement for completion. The user and downstream workflow receive a false terminal state.
Failure mode 7: Compensation is treated as rollback
An offsetting operation is presented as if it restored the prior state exactly. External observers, notifications, timing, and downstream effects may remain, while the compensation itself may require approval.
Failure mode 8: Tool results gain instruction authority
Returned text or metadata enters the agent's working context and is interpreted as a new command. Data from one action has bypassed the catalog and permission boundary for the next.
Failure mode 9: Delegation amplifies authority
A child worker receives broader tools, credentials, data, approval status, or delegation depth than its parent. Accountability blurs, and revocation can no longer propagate reliably.
Failure mode 10: Resumption repeats a confirmed effect
Two workers acquire the task, a stale checkpoint omits a receipt, or a late result arrives after takeover. In the absence of a lease and action ledger, each attempt concludes that dispatch is still necessary.
Failure mode 11: Cancellation is semantically vague
The interface says “cancelled” after the remote commit point. Planning may have stopped while an effect remains pending or has already completed. The result collapses three materially different states: cancelled before dispatch, cancellation requested, and completed despite cancellation.
Failure mode 12: Audit data cannot prove the outcome
Logs preserve model reasoning and transport status but omit the action version, principal, authorization, approval, effect identity, remote receipt, or reconciliation evidence. The team can explain the narrative but cannot prove what crossed the boundary.
8. Tradeoffs
General tools versus semantic actions
General tools reduce integration work and leave room for unanticipated tasks. That flexibility also exposes operations and parameters that are difficult to authorize or review. Recurring production workflows usually warrant semantic actions. Keep a general tool only inside a tightly bounded expert environment with explicit scope, consequence, and ownership.
Autonomy versus review burden
Human gates can contain exposure, but they also introduce latency, fatigue, and stale decisions. Approval earns that cost when informed judgment or accountable authority can change the outcome. Deterministic bounded execution is the better fit when consequence and parameter envelopes are genuinely narrow. A gate that reviewers pass without examining evidence is ceremony, not control.
Parameter flexibility versus enforceability
Letting the model choose targets and values increases task coverage while expanding the action surface combinatorially. A useful split is to leave low-risk expressive fields open to proposal and keep identity, tenant, environment, financial limits, and similar boundaries system-derived or policy-fixed.
Retry availability versus side-effect safety
A retry improves availability only when the prior effect is known absent or can be deduplicated safely. Reconciliation costs time, but duplicate consequence usually costs more. If a tool cannot provide stable receipts or status lookup, lower its autonomy tier or assign unknown outcomes to a human owner.
Reversibility versus user expectations
Drafts and compensating actions can reduce recovery cost, but “reversible” is usually conditional. A deleted message may already have been read, and revoked access cannot make viewed data unseen. Classify reversibility by external consequence rather than the presence of an inverse API.
Durable control versus implementation cost
Leases, checkpoints, action ledgers, and receipts add storage and coordination work. Their value rises with duration, cost, consequence, and asynchronous behavior; a short read-only request may need far less machinery. Scale the controls to consequence, ambiguity, and recovery cost.
Rich receipts versus sensitive-data exposure
Receipts need enough detail for accountability without becoming copies of sensitive payloads. Stable resource references, redacted previews, material digests, decision identities, and access-controlled evidence links usually provide that balance. Chapter 11 determines how those records are transported, retained, and queried.
9. Production Checklist
Before approving a tool or agentic workflow, confirm:
- Every executable operation is defined as a semantic action with a versioned tool contract.
- The action names the initiating principal, represented principal where applicable, purpose, accountable owner, target, consequence, and reversibility.
- The executing credential is narrower than or equal to the effective permission decision.
- Every material parameter declares source, model influence, constraints, canonicalization, and protected status.
- Tool defaults and ignored parameters cannot widen the canonical action.
- Authorization, approval, effect identity, and dispatch use the same action version and digest.
- Explicit denies, indeterminate authority, and stale decisions fail closed at dispatch.
- Approval packets include exact targets, material values, evidence, uncertainty, consequence, reviewer authority, expiry, and allowed decisions.
- Material changes invalidate approval and trigger the required re-authorization or re-approval.
- Side-effecting actions declare commit point, acknowledgement, completion, partial-success, cancellation, and compensation semantics.
- Idempotency identity has a defined owner, derivation, scope, retention window, and parameter-conflict behavior.
- Unknown outcomes reconcile against an authoritative receipt or status interface before repeat execution.
- Compensation is treated as a separate effect with its own authority and failure behavior.
- Delegation attenuates authority, preserves provenance, limits depth and budget, and propagates revocation.
- Long-running tasks have durable task and attempt identities, a single-writer rule, checkpoints, an action ledger, and safe resumption.
- Stale authority, credentials, intent, or approval stops long-running execution until renewed.
- Tool results retain provenance, freshness, completeness, trust, and resource-scope labels.
- Returned data cannot introduce executable instructions by default.
- Every consequential action produces a structured receipt relating proposal, permission, approval, dispatch, and known outcome.
- Action-local checks cover the invariants below; broader evaluation remains in Chapter 8.
10. Design Review Questions
- What new external effect becomes possible when this tool is enabled?
- What semantic action does the workflow need, and what broader operations can be withheld?
- Who is the initiating principal, who, if anyone, is represented, and who owns the consequence?
- Which authoritative decision permits the action for this purpose, target, environment, and time?
- Which parameters are user-supplied, model-proposed, system-derived, policy-fixed, protected, or tool-returned?
- Can canonicalization, a default, or an ignored field expand target scope or consequence?
- What exact object is authorized and approved, and what material change invalidates those decisions?
- What evidence and uncertainty does the reviewer see, and what decisions may the reviewer make?
- Where is the external commit point, and what does acknowledgement prove?
- What does partial success mean for this operation and for the user-visible outcome?
- Who owns the idempotency key, what operation does it identify, and how long is it honored?
- What happens when the same key is reused with different parameters?
- How does the system reconcile a timeout, disconnect, late result, or unknown outcome?
- Is compensation actually available, and what consequence or authority does it introduce?
- Can delegation increase tools, data scope, consequence, depth, or inherited approval?
- How do cancellation and revocation propagate to active and delegated work?
- What prevents two workers or a resumed task from dispatching the same effect?
- When must a long-running task renew authority, approval, credential, or user intent?
- What properties of a tool result are trusted, and can returned content influence later action?
- What receipt proves the authorized action and its confirmed, partial, unknown, compensated, or failed outcome?
11. Main Artifact: Tool Permission Matrix
The Tool Permission Matrix is a coordinated specification for action authority. Review its views together: separating principal, parameters, approval, effect safety, delegation, long-running execution, and outcome proof keeps each table readable, but none is sufficient alone. Stable action identities join the views.
Artifact header
- Tool Permission Matrix identity and version:
- Workflow and owner:
- Initiating and represented-principal model:
- Accountable consequence owner:
- Source AI Fit and Risk Assessment Worksheet identity, version, and accepted decision IDs:
- Source Harness Control-Loop Diagram identity, version, and action-ready boundary:
- Authoritative permission and policy decision identity, version, and expiry:
- Evaluation Plan handoff: action invariants, outcome states, and scenario IDs:
- AI Threat Model handoff: action boundary, protected assets, and unresolved threats:
- AI Release Manifest handoff: tool-contract identities and compatibility classification:
- Approval date:
- Safe behavior when authority or outcome is indeterminate:
View 1: Action catalog
| Action ID | Semantic action and tool contract | Effect class | Target and environment | Consequence / reversibility | Preconditions and postcondition | Explicitly excluded operations |
|---|---|---|---|---|---|---|
| ACT-01 | Observe / prepare / write / notify / execute |
Name semantic operations rather than endpoints. “Append internal case note,” for example, must not silently include changing ownership, status, or external visibility.
View 2: Authority matrix
| Action ID | Initiating / represented principals | Purpose | Resource / tenancy scope | Parameter envelope / limits | Executing capability | Decision ID / version / expiry | Approval rule | Explicit denies |
|---|---|---|---|---|---|---|---|---|
| ACT-01 |
The executing capability cannot extend effective scope beyond the decision in its row. An indeterminate or expired decision blocks dispatch.
View 3: Parameter control map
| Action ID / parameter | Meaning / type | Source | Model influence | Allowed values / cross-field constraints | Canonicalization / freshness | Protected / display rule | Tool default / ignored-field behavior |
|---|---|---|---|---|---|---|---|
| ACT-01 / target_id | User / model / system / policy / tool | Propose / select / transform / none |
Mark tenant, environment, credential, authorization reference, and other boundary values as protected wherever model influence is prohibited. Reject a tool that silently ignores a constrained value or substitutes a broader default.
View 4: Approval binding
| Action ID | Approval trigger | Exact reviewed snapshot | Evidence and uncertainty | Consequence preview / diff | Reviewer authority | Allowed decisions | Digest / freshness | Invalidation conditions |
|---|---|---|---|---|---|---|---|---|
| ACT-01 | Target, material parameters, principal, expected effect | Approve / reject / edit / narrow / escalate |
A plan approval may authorize preparation, but it cannot cover material values selected later. Record whether any reviewer edit creates a new proposal or whether a narrowly defined edit may be canonicalized into a new action version.
View 5: Effect-safety contract
| Action ID | Effect identity / deduplication scope | Commit point | Acknowledgement versus completion | Partial-success semantics | Unknown-outcome reconciliation | Cancellation / late results | Compensation / limits |
|---|---|---|---|---|---|---|---|
| ACT-01 |
Also record the idempotency-key owner, derivation inputs, retention window, and the response to one key appearing with different canonical parameters. Claim exactly-once execution only if the complete boundary can prove it.
View 6: Delegation envelope
| Parent action / delegation ID | Delegate objective | Allowed and withheld authority | Data and resource scope | Parameter / consequence limits | Depth, budget, deadline | Approval inheritance | Result and acceptance authority | Revocation behavior |
|---|---|---|---|---|---|---|---|---|
Keep inherited approval action-specific. A delegate may inherit permission to prepare a proposal while still needing a new decision before dispatch.
View 7: Long-running task contract
| Workflow / action ID | Task and attempt identity | Lease or single-writer rule | Checkpoint and safe resume boundary | Action ledger states | Authority renewal | Cancellation / supersession / takeover | Terminal result owner |
|---|---|---|---|---|---|---|---|
| Proposed / dispatched / confirmed / unknown / compensated |
These durable facts define progress. Before a resumed attempt issues a replacement action, it must reconcile every ledger entry that was dispatched but remains unconfirmed.
View 8: Action receipt contract
Every material action receipt should contain:
- workflow, execution, action, action-version, attempt, and correlation identities
- initiating and represented principal, accountable owner, and delegation chain
- semantic operation, tool-contract version, target references, and material parameter digest
- permission-rule identity, authorization decision, and approval reference
- action digest, idempotency identity, and dispatch timestamp
- acknowledgement and stable remote operation or receipt identifier
- outcome: confirmed, partial, unknown, compensated, rejected, cancelled-before-dispatch, or terminally failed
- postcondition, reconciliation, or compensation evidence reference
- decision origin and timestamps
Free-form explanation may accompany the receipt; it cannot replace the structured record.
View 9: Action-local checks
Before accepting the matrix, verify:
- every executable action resolves an effective principal and current authoritative decision
- protected parameters cannot be supplied, replaced, or expanded by the model
- canonicalization cannot widen the permitted resource, environment, audience, quantity, or consequence
- changing any material field invalidates the prior action digest and bound approval
- reusing an idempotency identity with different canonical parameters is rejected
- dispatched-but-unconfirmed actions reconcile before any repeat
- acknowledgement, partial completion, unknown outcome, and confirmed effect cannot be mislabeled as one another
- cancellation before dispatch prevents the effect and post-dispatch cancellation has explicit semantics
- compensation requires declared authority and cannot be represented as perfect rollback by default
- delegated authority is a subset of parent authority and cannot bypass approval
- a resumed or concurrent task cannot repeat a confirmed effect
- stale authorization, approval, credential, or represented-principal intent blocks continuation
- tool results remain data unless a separately authorized boundary promotes them
- every terminal outcome can be related to a structured receipt and stable evidence
These checks are action-contract invariants, not a full evaluation plan. Chapter 8 turns them into representative scenarios, regressions, adversarial cases, human rubrics, and launch thresholds. Chapter 11 defines how receipts and events are retained, queried, alerted on, and used in operations.
The Tool Permission Matrix consumes accepted consequence and authority limits from the AI Fit and Risk Assessment Worksheet and the exact action-ready boundary from the Harness Control-Loop Diagram. Its action invariants and outcome semantics pass to the Evaluation Plan; protected action surfaces and unresolved threats pass to the AI Threat Model; versioned tool contracts pass to the AI Release Manifest. A receiving artifact may restrict exposure or demand stronger proof, but it cannot silently broaden the principals, targets, parameters, delegation, approval scope, or repeat semantics defined here.
12. Key Takeaways
- Treat a tool call as a proposed authority crossing; selecting a tool cannot mint permission.
- Use one versioned action for canonicalization, authorization, approval, effect identity, and dispatch.
- Make parameter provenance and protected fields explicit because they determine the model's effective authority.
- Define commit, acknowledgement, completion, partial success, cancellation, reconciliation, and compensation for every side-effecting action that can encounter them.
- Use idempotency to prevent or recognize repeated intent; treat compensation as a separate effect, never as perfect rollback.
- Bind approval to an exact action, evidence snapshot, consequence, reviewer authority, and freshness window.
- Attenuate authority through delegation, and renew it during long-running execution while preventing duplicate effects.
- Rely on structured receipts to prove what was allowed, dispatched, and confirmed. Model narration cannot provide that proof.
- Use the Tool Permission Matrix to expose excessive authority, mutable approvals, unsafe repeats, ambiguous outcomes, and undefined recovery in one production review.