Policy and Invocation

Tool invocation is a runtime operation, not a direct function call from an agent. AGH validates the input, applies policy, dispatches the tool, redacts sensitive fields, and returns a structured result.

Invocation lifecycle

Rendering diagram...

Tool invocation flows through validation, policy, dispatch, redaction, and audit instead of bypassing the daemon.

CLI invocation

Invoke with inline JSON:

agh tool invoke agh__tool_info --input '{"tool_id":"agh__skill_view"}' -o json

Invoke with a file:

agh tool invoke agh__tool_info --input-file ./input.json -o json

Invoke with stdin:

echo '{"tool_id":"agh__skill_view"}' | agh tool invoke agh__tool_info -o json

What happened: the CLI sent JSON input to the daemon, the daemon validated and dispatched the tool, and the response came back as structured output.

Scoped diagnostics

Some tools depend on workspace, session, or agent context. Pass scope when you need diagnostics for the same view a managed session would receive:

agh tool info agh__skill_view --workspace ws-1 --session sess-1 --agent reviewer -o json

Use scoped diagnostics when:

a tool is visible globally but unavailable inside a session
a workspace-specific resource should appear but does not
an agent-specific toolset is narrower than the operator view
a policy decision depends on the active session context

Approval-gated tools

Some tools may require approval before execution. When a tool requires approval, the descriptor and diagnostics should tell the caller what is missing. The invocation path accepts a single-use approval token:

agh tool invoke <tool-id> \
  --approval-token "$APPROVAL_TOKEN" \
  --input '{"target":"example"}' \
  -o json

Do not persist approval tokens in memory, docs, logs, bridge messages, or task descriptions. Treat them as short-lived credentials.

Sensitive input fields

If input contains sensitive values, mark the field path so invocation evidence can redact it:

agh tool invoke <tool-id> \
  --input '{"secret_ref":"vault://provider/token"}' \
  --sensitive-input-field secret_ref \
  -o json

What happened: AGH still received the input needed by the handler, but the specified field is treated as sensitive in diagnostic and event surfaces.

Common failures

Symptom	Likely cause	First check
Tool is not found	Wrong ID or tool not registered in the current runtime.	`agh tool search <query> -o json`
Tool is visible but unavailable	Missing workspace/session/agent scope or prerequisite configuration.	`agh tool info <tool-id> --session <id> -o json`
Invocation rejects input	JSON does not match the tool schema.	`agh tool info <tool-id> -o json`
Invocation needs approval	Policy requires an approval token.	Descriptor diagnostics
Result omits expected secret value	Secrets are write-only or redacted by design.	Vault and policy docs