Phone Retrieval

Phone retrieval

Some facts are only available by asking. Whether a part is on the shelf right now, what a repair will actually cost, how long a lead time really is, whether the shop is open on the public holiday next week. The web has the number; it does not have the answer.

This skill calls the businesses, asks the same questions of each, and returns a structured record per business — every requested field scored, with the transcript as evidence.

When to use

• The answer changes faster than a website does: stock, price today, lead time.
• The answer was never published: whether they will hold an item, whether a particular service is offered.
• Several places need the same question and the answers need comparing.

When not to use

• The answer is on the web. Look there first.
• The task requires committing to something — placing an order, making a booking, agreeing a price. This skill retrieves; it does not commit.
• The number belongs to a private individual. See references/safety.md.

Side effects

This skill places real outbound phone calls to real businesses, and each call costs money. A call cannot be recalled once placed. Planning is free and does not dial; only the run step places a call, and only after a human approves it.

It writes local state — one record per plan and per run, plus the call result — to .calle-runs/ by default (CALL_STATE_DIR to change it). These files are created owner-only and they hold the transcript.

Phone numbers are masked on disk as well as in output. A sidecar is backed up, synced, screenshotted and pasted into issues like any other file, so a number quoted back inside a transcript turn is the same disclosure wherever it sits. Set CALL_STATE_FULL=1 if you need the unmasked number in your own records — for instance to tell which of several businesses a four-day-old record belongs to. It is off by default.

⚠️ Owner-only is a POSIX guarantee. On Windows the files are created with whatever the filesystem gives them; if that matters to you, put the state directory somewhere with appropriate access control.

Setup

Python 3.11+. Nothing else for the no-call path.

The fake provider is the default. Out of the box this skill cannot ring a phone: CALL_PROVIDER defaults to fake, which never dials and needs no account, no credentials and no network. Selecting the live provider is an explicit act.

python scripts/call_agent.py plan \
    --to +15550101234 \
    --callee-name "Miller Hardware" \
    --purpose "Check availability before travelling" \
    --field "in_stock=Do you have it" \
    --field "unit_price=What does it cost"

Then run --plan-id ..., status --run-id ..., and show <id>, which follows a plan to its run and returns the stored result. The full sequence writes the same local records a real call would.

To see what the skill is actually for, set CALL_FAKE_REWRITE before planning: added, merged, referent, dropped or normalised. Each makes the fake return a plan whose text differs from what was sent, in one of the four ways worth reporting — plus one that is harmless. Compare goal_sent against display_goal in the stored plan record. See references/goal-inspection.md.

Placing real calls

Requires a CALL-E account and their CLI; point CALLE_BIN at it if it is not on the default path. Then, and only then:

CALL_PROVIDER=calle python scripts/call_agent.py plan ...

⚠️ That variable is the only thing between this tool and a real phone. It is not set by default, and it should not be set in a shell profile or a wrapper script — set it on the command that is meant to dial.

Tests

python scripts/test_call_agent.py

No credentials, no network. Asserts on side effects — how many times the provider was submitted to, what mode files were created with, what ended up on disk — rather than only on return values.

Workflow

1. Establish the fields before dialling

Write down what you are asking for, as discrete fields, before any call is planned. in stock, unit price, lead time in days, open Saturday.

One call answers a handful of fields well and a dozen badly. If the list runs long, the task is really two tasks.

Every field must be answerable in a sentence by someone standing at a counter. If a field needs the callee to go and look something up, expect it to come back unanswered.

2. Plan

Planning is free and does not dial.

python scripts/call_agent.py plan \
    --to +15550101234 \
    --callee-name "Miller Hardware" \
    --purpose "Check availability and price before travelling" \
    --field "in stock" \
    --field "unit price"

--callee-name is required. It is the business name said aloud at the open — "have I reached Miller Hardware?" — so give it as a person would say it, not as a directory listing. Without it the opening has nothing to substitute and the agent may recite the instruction to the callee instead of performing it.

The plan comes back with an identifier and a confirmation token.

3. Inspect the returned goal

Read the plan's display_goal before anything is approved.

The provider does not send your text to the callee. It rewrites it, and the rewritten version is what the agent works from. Most rewriting is harmless normalisation. Four kinds are not: something added, a prohibition merged, a prohibition's referent changed, a field dropped or re-ordered.

Full detail, and what this check does not tell you: references/goal-inspection.md.

4. Get a human's approval

Never run a plan the operator has not approved. One call, one yes.

One plan carries one number. A confirmation token authorises the whole plan it belongs to, and a call already in flight cannot be cancelled — so the only recipient count where the approval and the irrevocable action correspond exactly is one. Calling several businesses means planning and approving each one. That costs an approval per call, and that is the point.

Show the operator what will be dialled, what will be asked, and anything the goal inspection turned up. Approval is for this plan, on this number, now.

The confirmation token authorises a real, charged call and cannot be revoked early. It stays in local state. This skill never prints it, never returns it from plan, and never writes it to a result file.

5. Run

python scripts/call_agent.py run --plan-id <id>

Never retry a run. If a run appears to have failed, find out what happened before doing anything else. A call that reports failure may still have been placed, and a blind retry calls a real business a second time. Check the status of the existing run; do not submit a new one.

6. Read the result

The transcript is authoritative. The summary is a repair aid. Where they disagree, the transcript wins.

Ignore the provider's confidence score. It reflects the model's confidence in its own summary, not whether the callee actually knew the answer.

Score every field you asked for. A field nobody asked about is not the same as a field that was asked and not answered, and neither is the same as a refusal.

⚠️ Structured extraction is best-effort. Fields are recovered by matching the key names you requested against the summary text. The provider is told to use those names and does not always do so. Nothing is inferred from prose — an answer parsed out of a sentence is an answer nobody gave — so when the keys are absent the adapter reports that rather than guessing. See extraction_status in the reporting step.