[vhmartinezm]

TL;DR

• polyswarm search ioc sha1|md5 <hash>: when the server refuses a hash that matches several artifacts (AMBIGUOUS_HASH), print a message listing the candidate sha256s and how to re-run, at exit 2, instead of a raw 400.
• Any other refusal is re-raised unchanged.
• search ioc help and specs/02-commands.md describe the behaviour.

Tests

New SearchIocByHashCliTest (sha1/md5 forwarded with their type; ambiguous md5 lists candidates at exit 2; other refusals not relabelled). Locally pytest tests: 241 passed; the 2 failures in tests/api_uri_test.py fail identically on origin/develop in my local environment.

Requires

polyswarm/artifact-index#2021 for the server behaviour. No SDK change or version bump is needed: the error shape is read from the existing RequestException (the SDK docs for it are in polyswarm/polyswarm-api#335, which this PR does not depend on).

[claude]

Review against AGENTS.md / specs

1. Spec drift: specs/05-sdk-contract.md §imports (line 21) names rules favorite as the only place that catches RequestException and reads exc.request.errors['code']. search ioc now catches it too and reads AMBIGUOUS_HASH (code, sha256s, truncated) off the same dict. Add this second call site and its fields to that row in this PR. AGENTS.md says to update the spec for every area you touch.

2. Test convention: the mock request can't catch a rename. _refused in tests/search_test.py builds the request with mock.Mock(). Spec 05 requires these refusal branches to be "unit-pinned against a real PolyswarmRequest (not a hand-built mock, which fabricates whatever attribute it is asked for and so cannot detect a rename)". Build a real PolyswarmRequest with errors filled in, as the rules favorite tests do.

3. Missing case: empty sha256s. If the server sends AMBIGUOUS_HASH with an empty or missing sha256s, the message ends with "…with one of:" and nothing after it. Fall back to text without the list, the way FAVORITE_LIMIT falls back when its counters are missing, and add a test for it.

4. Gitflow: base develop is correct and the version is unchanged. The head branch DN-8581 has a ticket prefix, so squash-merge with a clean subject to keep the ticket ID out of the merge commit (AGENTS.md § Commit + PR hygiene).

[claude]

No blocking issues. The AMBIGUOUS_HASH handling matches the FAVORITE_LIMIT pattern in client/rules.py. It exits 2 through the CLI PolyswarmException, other refusals are re-raised, and the tests use a real PolyswarmRequest as specs/05 requires. The spec updates in 02 and 05 are in this PR. Two small items:

• ## Requires: "polyswarm/polyswarm-api for the documented contract" doesn't link to anything. specs/05-sdk-contract.md and AGENTS.md ask you to link the SDK PR when the CLI depends on an unreleased SDK surface. If no SDK change is needed (the PR says the error is read from the existing RequestException), drop that half of the line. If one is needed, link the PR.
• Merge: the head branch is DN-8581. Per AGENTS.md, squash-merge with an explicit clean subject so the ticket ID doesn't land in develop history through the default merge subject.